Crate rustc_ast_lowering[−][src]

Expand description

Lowers the AST to the HIR.

Since the AST and HIR are fairly similar, this is mostly a simple procedure, much like a fold. Where lowering involves a bit more work things get more interesting and there are some invariants you should know about. These mostly concern spans and IDs.

Spans are assigned to AST nodes during parsing and then are modified during expansion to indicate the origin of a node and the process it went through being expanded. IDs are assigned to AST nodes just before lowering.

For the simpler lowering steps, IDs and spans should be preserved. Unlike expansion we do not preserve the process of lowering in the spans, so spans should not be modified here. When creating a new node (as opposed to “folding” an existing one), create a new ID using next_id().

You must ensure that IDs are unique. That means that you should only use the ID from an AST node in a single HIR node (you can assume that AST node-IDs are unique). Every new node must have a unique ID. Avoid cloning HIR nodes. If you do, you must then set the new node’s ID to a fresh one.

Spans are used for error messages and for tools to map semantics back to source code. It is therefore not as important with spans as IDs to be strict about use (you can’t break the compiler by screwing up a span). Obviously, a HIR node can only have a single span. But multiple nodes can have the same span and spans don’t need to be kept in order, etc. Where code is preserved by lowering, it should have the same span as in the AST. Where HIR nodes are new it is probably best to give a span for the whole AST node being lowered. All nodes should have real spans; don’t use dummy spans. Tools are likely to get confused if the spans from leaf AST nodes occur in multiple places in the HIR, especially for multiple identifiers.

Modules

The Rust abstract syntax tree module.

Functions dealing with attributes and meta items.

Definitions shared by macros / syntax extensions and e.g. rustc_middle.

HIR walker for walking the contents of nodes.

This module contains all the defined keyword Symbols.

A MutVisitor represents an AST modification; it accepts an AST piece and and mutates it in place. So, for instance, macro expansion is a MutVisitor that walks over an AST and modifies it.

The AST pointer.

This module contains all the defined non-keyword Symbols.

Token Streams

AST walker. Each overridden visit method has full control over what happens with its node, it can do its own traversal of the node’s children, call visit::walk_* to apply the default traversal algorithm, or prevent deeper traversal by doing nothing.

Macros

Constructs an event at the debug level.

Constructs an event at the trace level.

Structs

A path like Foo<'a, T>.

A constant (expression) that’s not an item or associated item, but needs its own DefId for type-checking, const-eval, etc. These are usually found nested inside types (e.g., array lengths) or expressions (e.g., repeat counts), and also used to define explicit discriminant values for enum variants.

An arm of a ‘match’.

A constraint on an associated type (e.g., A = Bar in Foo<A = Bar> or A: TraitA + TraitB in Foo<A: TraitA + TraitB>).

Metadata associated with an item.

A block ({ .. }).

A DefId identifies a particular definition, by combining a crate index and a def index.

A unique identifier that we can use to lookup a definition precisely. It combines the index of the definition’s parent (if any) with a DisambiguatedDefPathData.

A DefPathHash is a fixed-size representation of a DefPath that is stable across crate and compilation session boundaries. It consists of two separate 64-bit hashes. The first uniquely identifies the crate this DefPathHash originates from (see StableCrateId), and the second uniquely identifies the corresponding DefPath within that crate. Together they form a unique identifier within an entire crate graph.

The definition table containing node definitions. It holds the DefPathTable for LocalDefIds/DefPaths. It also stores mappings to convert LocalDefIds to/from HirIds.

A unique ID associated with a macro invocation and expansion.

An expression.

A single field in a struct expression, e.g. x: value and y in Foo { x: value, y }.

Field definition in a struct, variant or union.

A signature (not the body) of a function declaration.

A function header.

Represents a function’s signature in a trait declaration, trait implementation, or free function.

Foreign module declaration.

Helper struct for delayed construction of GenericArgs.

Represents lifetime, type and const parameters attached to a declaration of a function, enum, trait, etc.

Inline assembly.

An item definition.

A “Label” is an identifier of some point in sources, e.g. in the following code:

A “Lifetime” is an annotation of the scope in which variable can be used, e.g. 'a in &'a i32.

An AST literal.

LLVM-style inline assembly.

LLVM-style inline assembly.

Local represents a let statement, e.g., let <pat>:<ty> = <expr>;.

A LocalDefId is equivalent to a DefId with krate == LOCAL_CRATE. Since we encode this information in the type, we can ensure at compile time that no DefIds from upstream crates get thrown into the mix. There are quite a few cases where we know that only DefIds from the local crate are expected and a DefId from a different crate would signify a bug somewhere. This is when LocalDefId comes in handy.

Represents a macro invocation. The path indicates which macro is being invoked, and the args are arguments passed to it.

Represents a macro definition.

A spanned compile-time attribute item.

Identifies an AST node.

A parameter in a function header.

A path like Foo(A, B) -> C.

The result of resolving a path before lowering to HIR, with “module” segments resolved and associated item segments deferred to type checking. base_res is the resolution of the resolved part of the path, unresolved_segments is the number of unresolved segments.

A match pattern.

A single field in a struct pattern.

A “Path” is essentially Rust’s notion of a name.

A segment of a path: an identifier, an optional lifetime, and a set of types.

Just a helper ‒ separate structure for each namespace.

The explicit Self type in a “qualified path”. The actual path, including the trait and the associated item, is stored separately. position represents the index of the associated item qualified with this Self type.

Represents the data associated with a compilation session for a single crate.

A Vec-like container that can store a small number of elements inline.

SortedMap is a data structure with similar characteristics as BTreeMap but slightly different trade-offs: lookup, insertion, and removal are O(log(n)) and elements can be iterated in order cheaply.

A compressed span.

When hashing something that ends up affecting properties like symbol names, we want these symbol names to be calculated independently of other factors like what architecture you’re compiling from.

This is the context state available during incr. comp. hashing. It contains enough information to transform DefIds and HirIds into stable DefPaths (i.e., a reference to the TyCtxt) and it holds a few caches for speeding up various things (e.g., each DefId/DefPath is only hashed once).

A statement

Same as Lit, but restricted to string literals.

An interned string.

A TokenStream is an abstract sequence of tokens, organized into TokenTrees.

TraitRefs appear in impls.

A tree of paths sharing common prefixes. Used in use items both at top-level and inside of braces in import groups.

Enum variant.

A type bound.

A where-clause in a definition.

An equality predicate (unsupported).

A lifetime predicate.

A single-threaded reference-counting pointer. ‘Rc’ stands for ‘Reference Counted’.

Enums

Either an argument for a parameter e.g., 'a, Vec<u8>, 0, or a constraint on an associated item, e.g., Item = String or Item: Bound.

What to do when we encounter an anonymous lifetime reference. Anonymous lifetime references come in two flavors. You have implicit, or fully elided, references to lifetimes, like the one in &T or Ref<T>, and you have '_ lifetimes, like &'_ T or Ref<'_, T>. These often behave the same, but not always:

Indicates the confidence in the correctness of a suggestion.

Represents associated item kinds.

The kinds of an AssocTyConstraint.

Distinguishes between Attributes that decorate items and Attributes that are contained as statements within items. These two cases need to be distinguished for pretty-printing.

The kind of borrow in an AddrOf expression, e.g., &place or &raw const place.

A capture clause used in closures and async blocks.

What kind of definition something is; e.g., mod vs struct.

Item defaultness. For details see the RFC #2532.

The kind of compiler desugaring.

The edition of the compiler. (See RFC 2052.)

extern qualifier on a function item or function type.

An item in extern block.

Concrete argument in the sequence of generic args.

The arguments of a path segment.

The AST represents all type param bounds as types. typeck::collect::compute_bounds matches these against the “special” built-in traits (see middle::lang_items) and detects Copy, Send and Sync.

Context of impl Trait in code, which determines whether it is allowed in an HIR subtree, and if so, what meaning it has.

Position in which impl Trait is disallowed.

Inline assembly operand.

Inline assembly operand explicit register or register class.

Is the trait definition an auto trait?

Type of the float literal based on provided suffix.

Type of the integer literal based on provided suffix.

Literal kind.

Inline assembly dialect.

Arguments passed to an attribute or a function-like macro.

A compile-time attribute item.

Module item kind.

The movability of a generator / closure literal: whether a generator contains self-references, causing it to be !Unpin.

Different kinds of symbols can coexist even if they share the same textual name. Therefore, they each have a separate universe (known as a “namespace”).

Possible values inside of compile-time attribute lists.

Specifies the enforced ordering for generic parameters. In the future, if we wanted to relax this order, we could override PartialEq and PartialOrd, to allow the kinds to be unordered.

All the different flavors of pattern that Rust recognizes.

Limit types of a range (inclusive or exclusive)

The resolution of a path or export.

Alternative representation for Args describing self parameter of methods.

When the main Rust parser encounters a syntax-extension invocation, it parses the arguments to the invocation as a token tree. This is a very loose structure, such that all sorts of different AST fragments can be passed to syntax extensions using a uniform type.

A modifier on a bound, e.g., ?Sized or ~const Trait.

Syntax used to declare a trait object.

The various kinds of type recognized by the compiler.

Unary operator.

Part of use item to the right of its prefix.

Fields and constructor ids of enum variants and structs.

A single predicate in a where-clause.

Constants

The NodeId used to represent the root of the crate.

When parsing and at the beginning of doing expansions, we initially give all AST nodes this dummy AST NodeId. Then, during a later phase of expansion, we renumber them to have small, positive IDs.

Dummy span, both position and length are zero, syntax context is zero as well.

Statics

The bare_trait_objects lint suggests using dyn Trait for trait objects.

Traits

An AstLike represents an AST node (or some wrapper around and AST node) which stores some combination of attributes and tokens.

“Signaling” trait used in impl trait to tag lifetimes that you may need to capture but don’t really need for other reasons. Basically a workaround; see this comment for details.

Something that implements HashStable<CTX> can be hashed in a way that is stable across multiple compilation sessions.

Requirements for a StableHashingContext to be used in this crate. This is a hack to allow using the HashStable_Generic derive macro instead of implementing everything in rustc_middle.

Represents some newtyped usize wrapper.

Functions

Type Definitions

Represents associated items. These include items in impl and trait definitions.

A list of attributes.

Type alias for a hashmap using the fx hash algorithm.