macroonz-compiler 0.2.0

Deterministic Rust code generation for procedural macros: plan, render, close, explain, and bind one sealed expansion from declared input.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

//! The one grammar every line a compiler is handed is composed in.
//!
//! `<prefix>: <class>: <first established issue>[<body>][<site>]`, and there is no second composition anywhere in this crate.
//! Two grammars for one compiler is two shapes a reader has to learn, and the second one is always the one that drifts — it is the one no law was written against.
//!
//! The line is a SUMMARY and says so: the first established issue in full, then how many others there were, then whether the set that names them kept all of them, then where the refusal sits if it sits anywhere narrower than the declaration.
//! The remainder is not lost — every issue has its own identity in the related set, and the typed body is the value the caller of the refusing step holds.

use super::types::DiagnosticProjection;
use super::{
    IntrinsicRefused, Line, LineBody, LineSite, Placement, Refused, RelatedSet, Route, Site,
    SiteCoordinate,
};
use crate::bounded::Capping;
use crate::request::Door;
use crate::token::CoordinateRole;

/// The word one coordinate role counts its positions in.
///
/// Exhaustive on purpose, so a third role stops compiling here rather than being shown under a second role's word.
const fn coordinate_role_word(role: CoordinateRole) -> &'static str {
    match role {
        CoordinateRole::Byte => "byte",
        CoordinateRole::SemanticOrigin => "semantic-origin position",
    }
}

/// How much of a body one line is not carrying, composed from the typed body.
///
/// A capped body examined every issue it established and knows exactly how many it has no room for, so the clause says that rather than telling a reader to re-run a pass that already covered everything.
fn body_clause(body: LineBody) -> String {
    let (further, capping) = match body {
        LineBody::SingleCause => return String::new(),
        LineBody::Body { further, capping } => (further, capping),
    };
    let more = if further > 0 {
        format!(" (and {further} further established issues)")
    } else {
        String::new()
    };
    let kept = match capping {
        Capping::Complete => String::new(),
        Capping::Truncated { omitted } => format!(
            " (every issue was established; {omitted} of them do not fit the declared issue bound)"
        ),
    };
    format!("{more}{kept}")
}

/// Where one line says the refusal sits, composed from the typed coordinate.
///
/// The role travels with the position, so a byte offset never reads as a token ordinal and an ordinal never reads as a byte.
/// Where the producer's table does not reach the handle the clause is that refusal's own rendering: the locating half is missing and the reader is told so, rather than handed a number that means nothing.
fn site_clause(site: LineSite) -> String {
    match site {
        LineSite::WholeDeclaration => String::new(),
        LineSite::At(SiteCoordinate::Resolved(coordinate)) => {
            let word = coordinate_role_word(coordinate.role);
            let position = coordinate.position;
            format!(" (at {word} {position})")
        }
        LineSite::At(SiteCoordinate::NotReached(refusal)) => format!(" ({refusal})"),
    }
}

/// Compose the one line a compiler is handed.
///
/// Every part is read off a typed value — the door's prefix, the class's own sentence, the first issue as the refusing home stated it, and the clauses the body and the site compose — and no phrase here restates any of them in other words.
#[must_use]
pub fn composed(door: &Door, line: &Line<'_>, site: LineSite) -> String {
    let prefix = door.prefix();
    let class = line.class.described();
    let first = line.first;
    let stated_body = body_clause(line.body);
    let stated_site = site_clause(site);
    format!("{prefix}: {class}: {first}{stated_body}{stated_site}")
}

/// One composed line, with the related set's own capping written into it.
///
/// A complete set adds nothing: the line already reads as a summary of a complete body.
/// A capped set says so and says by how much, because the typed capping beside it is not something a compiler shows, and a reader given only the body's own identity would otherwise take the coarser commitment for the full one.
pub(crate) fn witnessed(line: &str, capping: Capping) -> String {
    match capping {
        Capping::Complete => line.to_owned(),
        Capping::Truncated { omitted } => format!(
            "{line} (the related set was capped at the declared issue bound: one identity over the \
             complete body is carried and {omitted} per-issue identities are not)"
        ),
    }
}

/// Project one refusal and its lawful site into every informed value the diagnostic carries.
pub(super) fn diagnostic<E: Refused>(refusal: &E, door: &Door, site: Site) -> DiagnosticProjection {
    let related = RelatedSet::derived_over(E::FAMILY, &refusal.related());
    let first = refusal.first();
    let line = Line {
        class: refusal.class(),
        first: &first,
        body: refusal.body(),
    };
    let composed_line = composed(door, &line, line_site(site));
    DiagnosticProjection {
        phase: E::PHASE,
        site,
        observed: refusal.observed(),
        summary: witnessed(&composed_line, related.capping()),
        expected: door.grammar(),
        related,
        repairs: refusal.repairs(),
        route: Route::through(door.entry()),
    }
}

/// Project one caller-supplied placement into the site it states.
pub(super) fn placement_site(placement: &Placement<'_>) -> Site {
    match *placement {
        Placement::WholeDeclaration => Site::whole_declaration(),
        Placement::AtToken { token, spans } => {
            Site::at_token(token, SiteCoordinate::answered(spans.coordinate_of(token)))
        }
    }
}

/// Project the intrinsic site carried by a refusal whose placing act already settled it.
pub(super) fn intrinsic_site<E: IntrinsicRefused>(refusal: &E) -> Site {
    refusal.site()
}

/// Project one diagnostic site into the posture its human-readable line carries.
fn line_site(site: Site) -> LineSite {
    match site {
        Site::WholeDeclaration => LineSite::WholeDeclaration,
        Site::AtToken { coordinate, .. } => LineSite::At(coordinate),
        Site::BeforeCapture { coordinate } => LineSite::At(SiteCoordinate::Resolved(coordinate)),
    }
}