wright/ast/mod.rs
1//! [Abstract syntax tree] modeling.
2//!
3//! These models are produced by the [parser](crate::parser), which lowers the lossless concrete syntax tree into
4//! these more convenient structures. Every node keeps track of the [Fragment] of source code it was parsed from, so
5//! later stages (type checking, code generation, etc.) can produce diagnostics pointing at the right code.
6//!
7//! The AST is designed to be produced even from source code with syntax errors. Pieces that are missing or could not
8//! be parsed show up as [ExprKind::Error](expr::ExprKind::Error), [Type::Error](ty::Type::Error), or
9//! [missing identifiers](identifier::Identifier::is_missing). In those cases the parser will always have emitted at
10//! least one error diagnostic.
11//!
12//! [Abstract syntax tree]: https://en.wikipedia.org/wiki/Abstract_syntax_tree
13
14use crate::source_tracking::fragment::Fragment;
15
16pub mod decl;
17pub mod expr;
18pub mod identifier;
19pub mod literal;
20pub mod path;
21pub mod stmt;
22pub mod ty;
23
24/// Common functionality for nodes in the AST.
25pub trait AstNode {
26 /// Get the [Fragment] of source code this node was parsed from.
27 fn matching_source(&self) -> &Fragment;
28}
29
30/// A doc comment (`///`, `//!`, `/** */`, or `/*! */`) attached to an item or source file.
31#[derive(Clone, Debug, PartialEq)]
32pub struct DocComment {
33 /// The full source of the comment, including the comment markers.
34 pub matching_source: Fragment,
35
36 /// The text of the comment, without the comment markers (`///`, `/**`, `*/`, etc.).
37 pub text: String,
38}
39
40impl DocComment {
41 /// Construct a [DocComment] from the [Fragment] of a doc comment token, stripping the comment markers.
42 pub fn from_fragment(matching_source: Fragment) -> Self {
43 let raw = matching_source.as_str();
44
45 let text = if let Some(line) = raw.strip_prefix("///").or_else(|| raw.strip_prefix("//!")) {
46 line
47 } else {
48 let without_start = raw
49 .strip_prefix("/**")
50 .or_else(|| raw.strip_prefix("/*!"))
51 .unwrap_or(raw);
52
53 without_start.strip_suffix("*/").unwrap_or(without_start)
54 };
55
56 DocComment {
57 text: text.to_owned(),
58 matching_source,
59 }
60 }
61}
62
63impl AstNode for DocComment {
64 fn matching_source(&self) -> &Fragment {
65 &self.matching_source
66 }
67}
68
69/// An entire parsed source file -- the root of the AST.
70#[derive(Clone, Debug, PartialEq)]
71pub struct SourceFile {
72 /// The whole source file.
73 pub matching_source: Fragment,
74
75 /// Inner doc comments (`//!` and `/*! */`) documenting the file as a whole.
76 pub docs: Vec<DocComment>,
77
78 /// The items declared in this file, in order.
79 pub items: Vec<decl::Item>,
80}
81
82impl AstNode for SourceFile {
83 fn matching_source(&self) -> &Fragment {
84 &self.matching_source
85 }
86}