naga/
span.rs

1use alloc::{
2    borrow::ToOwned,
3    format,
4    string::{String, ToString},
5    vec::Vec,
6};
7use core::{error::Error, fmt, ops::Range};
8
9use crate::{error::replace_control_chars, Arena, Handle, UniqueArena};
10
11/// A source code span, used for error reporting.
12#[derive(Clone, Copy, Debug, PartialEq, Default)]
13#[cfg_attr(feature = "arbitrary", derive(arbitrary::Arbitrary))]
14pub struct Span {
15    start: u32,
16    end: u32,
17}
18
19impl Span {
20    pub const UNDEFINED: Self = Self { start: 0, end: 0 };
21
22    /// Creates a new `Span` from a range of byte indices
23    ///
24    /// Note: end is exclusive, it doesn't belong to the `Span`
25    pub const fn new(start: u32, end: u32) -> Self {
26        Span { start, end }
27    }
28
29    /// Returns a new `Span` starting at `self` and ending at `other`
30    pub const fn until(&self, other: &Self) -> Self {
31        Span {
32            start: self.start,
33            end: other.end,
34        }
35    }
36
37    /// Modifies `self` to contain the smallest `Span` possible that
38    /// contains both `self` and `other`
39    pub fn subsume(&mut self, other: Self) {
40        *self = if !self.is_defined() {
41            // self isn't defined so use other
42            other
43        } else if !other.is_defined() {
44            // other isn't defined so don't try to subsume
45            *self
46        } else {
47            // Both self and other are defined so calculate the span that contains them both
48            Span {
49                start: self.start.min(other.start),
50                end: self.end.max(other.end),
51            }
52        }
53    }
54
55    /// Returns the smallest `Span` possible that contains all the `Span`s
56    /// defined in the `from` iterator
57    pub fn total_span<T: Iterator<Item = Self>>(from: T) -> Self {
58        let mut span: Self = Default::default();
59        for other in from {
60            span.subsume(other);
61        }
62        span
63    }
64
65    /// Converts `self` to a range if the span is not unknown
66    pub fn to_range(self) -> Option<Range<usize>> {
67        if self.is_defined() {
68            Some(self.start as usize..self.end as usize)
69        } else {
70            None
71        }
72    }
73
74    /// Check whether `self` was defined or is a default/unknown span
75    pub fn is_defined(&self) -> bool {
76        *self != Self::default()
77    }
78
79    /// Return a [`SourceLocation`] for this span in the provided source.
80    pub fn location(&self, source: &str) -> SourceLocation {
81        let prefix = &source[..self.start as usize];
82        let line_number = prefix.matches('\n').count() as u32 + 1;
83        let line_start = prefix.rfind('\n').map(|pos| pos + 1).unwrap_or(0) as u32;
84        let line_position = self.start - line_start + 1;
85
86        SourceLocation {
87            line_number,
88            line_position,
89            offset: self.start,
90            length: self.end - self.start,
91        }
92    }
93}
94
95impl From<Range<usize>> for Span {
96    fn from(range: Range<usize>) -> Self {
97        Span {
98            start: range.start as u32,
99            end: range.end as u32,
100        }
101    }
102}
103
104impl core::ops::Index<Span> for str {
105    type Output = str;
106
107    #[inline]
108    fn index(&self, span: Span) -> &str {
109        &self[span.start as usize..span.end as usize]
110    }
111}
112
113/// A human-readable representation for a span, tailored for text source.
114///
115/// Roughly corresponds to the positional members of [`GPUCompilationMessage`][gcm] from
116/// the WebGPU specification, except
117/// - `offset` and `length` are in bytes (UTF-8 code units), instead of UTF-16 code units.
118/// - `line_position` is in bytes (UTF-8 code units), instead of UTF-16 code units.
119///
120/// [gcm]: https://www.w3.org/TR/webgpu/#gpucompilationmessage
121#[derive(Copy, Clone, Debug, PartialEq, Eq)]
122pub struct SourceLocation {
123    /// 1-based line number.
124    pub line_number: u32,
125    /// 1-based column in code units (in bytes) of the start of the span.
126    pub line_position: u32,
127    /// 0-based Offset in code units (in bytes) of the start of the span.
128    pub offset: u32,
129    /// Length in code units (in bytes) of the span.
130    pub length: u32,
131}
132
133/// A source code span together with "context", a user-readable description of what part of the error it refers to.
134pub type SpanContext = (Span, String);
135
136/// Wrapper class for [`Error`], augmenting it with a list of [`SpanContext`]s.
137#[derive(Debug, Clone)]
138pub struct WithSpan<E> {
139    inner: E,
140    spans: Vec<SpanContext>,
141}
142
143impl<E> fmt::Display for WithSpan<E>
144where
145    E: fmt::Display,
146{
147    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
148        self.inner.fmt(f)
149    }
150}
151
152#[cfg(test)]
153impl<E> PartialEq for WithSpan<E>
154where
155    E: PartialEq,
156{
157    fn eq(&self, other: &Self) -> bool {
158        self.inner.eq(&other.inner)
159    }
160}
161
162impl<E> Error for WithSpan<E>
163where
164    E: Error,
165{
166    fn source(&self) -> Option<&(dyn Error + 'static)> {
167        self.inner.source()
168    }
169}
170
171impl<E> WithSpan<E> {
172    /// Create a new [`WithSpan`] from an [`Error`], containing no spans.
173    pub const fn new(inner: E) -> Self {
174        Self {
175            inner,
176            spans: Vec::new(),
177        }
178    }
179
180    /// Reverse of [`Self::new`], discards span information and returns an inner error.
181    #[allow(clippy::missing_const_for_fn)] // ignore due to requirement of #![feature(const_precise_live_drops)]
182    pub fn into_inner(self) -> E {
183        self.inner
184    }
185
186    pub const fn as_inner(&self) -> &E {
187        &self.inner
188    }
189
190    /// Iterator over stored [`SpanContext`]s.
191    pub fn spans(&self) -> impl ExactSizeIterator<Item = &SpanContext> {
192        self.spans.iter()
193    }
194
195    /// Add a new span with description.
196    pub fn with_span<S>(mut self, span: Span, description: S) -> Self
197    where
198        S: ToString,
199    {
200        if span.is_defined() {
201            self.spans.push((span, description.to_string()));
202        }
203        self
204    }
205
206    /// Add a [`SpanContext`].
207    pub fn with_context(self, span_context: SpanContext) -> Self {
208        let (span, description) = span_context;
209        self.with_span(span, description)
210    }
211
212    /// Add a [`Handle`] from either [`Arena`] or [`UniqueArena`], borrowing its span information from there
213    /// and annotating with a type and the handle representation.
214    pub(crate) fn with_handle<T, A: SpanProvider<T>>(self, handle: Handle<T>, arena: &A) -> Self {
215        self.with_context(arena.get_span_context(handle))
216    }
217
218    /// Convert inner error using [`From`].
219    pub fn into_other<E2>(self) -> WithSpan<E2>
220    where
221        E2: From<E>,
222    {
223        WithSpan {
224            inner: self.inner.into(),
225            spans: self.spans,
226        }
227    }
228
229    /// Convert inner error into another type. Joins span information contained in `self`
230    /// with what is returned from `func`.
231    pub fn and_then<F, E2>(self, func: F) -> WithSpan<E2>
232    where
233        F: FnOnce(E) -> WithSpan<E2>,
234    {
235        let mut res = func(self.inner);
236        res.spans.extend(self.spans);
237        res
238    }
239
240    /// Return a [`SourceLocation`] for our first span, if we have one.
241    pub fn location(&self, source: &str) -> Option<SourceLocation> {
242        if self.spans.is_empty() || source.is_empty() {
243            return None;
244        }
245
246        Some(self.spans[0].0.location(source))
247    }
248
249    pub(crate) fn diagnostic(&self) -> codespan_reporting::diagnostic::Diagnostic<()>
250    where
251        E: Error,
252    {
253        use codespan_reporting::diagnostic::{Diagnostic, Label};
254        let diagnostic = Diagnostic::error()
255            .with_message(self.inner.to_string())
256            .with_labels(
257                self.spans()
258                    .map(|&(span, ref desc)| {
259                        Label::primary((), span.to_range().unwrap()).with_message(desc.to_owned())
260                    })
261                    .collect(),
262            )
263            .with_notes({
264                let mut notes = Vec::new();
265                let mut source: &dyn Error = &self.inner;
266                while let Some(next) = Error::source(source) {
267                    notes.push(next.to_string());
268                    source = next;
269                }
270                notes
271            });
272        diagnostic
273    }
274
275    /// Emits a summary of the error to standard error stream.
276    #[cfg(feature = "stderr")]
277    pub fn emit_to_stderr(&self, source: &str)
278    where
279        E: Error,
280    {
281        self.emit_to_stderr_with_path(source, "wgsl")
282    }
283
284    /// Emits a summary of the error to standard error stream.
285    #[cfg(feature = "stderr")]
286    pub fn emit_to_stderr_with_path(&self, source: &str, path: &str)
287    where
288        E: Error,
289    {
290        use codespan_reporting::{files, term};
291
292        let files = files::SimpleFile::new(path, replace_control_chars(source));
293        let config = term::Config::default();
294
295        cfg_if::cfg_if! {
296            if #[cfg(feature = "termcolor")] {
297                let writer = term::termcolor::StandardStream::stderr(term::termcolor::ColorChoice::Auto);
298            } else {
299                let writer = std::io::stderr();
300            }
301        }
302
303        term::emit(&mut writer.lock(), &config, &files, &self.diagnostic())
304            .expect("cannot write error");
305    }
306
307    /// Emits a summary of the error to a string.
308    pub fn emit_to_string(&self, source: &str) -> String
309    where
310        E: Error,
311    {
312        self.emit_to_string_with_path(source, "wgsl")
313    }
314
315    /// Emits a summary of the error to a string.
316    pub fn emit_to_string_with_path(&self, source: &str, path: &str) -> String
317    where
318        E: Error,
319    {
320        use codespan_reporting::{files, term};
321
322        let files = files::SimpleFile::new(path, replace_control_chars(source));
323        let config = term::Config::default();
324
325        let mut writer = crate::error::DiagnosticBuffer::new();
326        term::emit(writer.inner_mut(), &config, &files, &self.diagnostic())
327            .expect("cannot write error");
328        writer.into_string()
329    }
330}
331
332/// Convenience trait for [`Error`] to be able to apply spans to anything.
333pub(crate) trait AddSpan: Sized {
334    /// The returned output type.
335    type Output;
336
337    /// See [`WithSpan::new`].
338    fn with_span(self) -> Self::Output;
339    /// See [`WithSpan::with_span`].
340    fn with_span_static(self, span: Span, description: &'static str) -> Self::Output;
341    /// See [`WithSpan::with_context`].
342    fn with_span_context(self, span_context: SpanContext) -> Self::Output;
343    /// See [`WithSpan::with_handle`].
344    fn with_span_handle<T, A: SpanProvider<T>>(self, handle: Handle<T>, arena: &A) -> Self::Output;
345}
346
347impl<E> AddSpan for E {
348    type Output = WithSpan<Self>;
349
350    fn with_span(self) -> WithSpan<Self> {
351        WithSpan::new(self)
352    }
353
354    fn with_span_static(self, span: Span, description: &'static str) -> WithSpan<Self> {
355        WithSpan::new(self).with_span(span, description)
356    }
357
358    fn with_span_context(self, span_context: SpanContext) -> WithSpan<Self> {
359        WithSpan::new(self).with_context(span_context)
360    }
361
362    fn with_span_handle<T, A: SpanProvider<T>>(
363        self,
364        handle: Handle<T>,
365        arena: &A,
366    ) -> WithSpan<Self> {
367        WithSpan::new(self).with_handle(handle, arena)
368    }
369}
370
371/// Trait abstracting over getting a span from an [`Arena`] or a [`UniqueArena`].
372pub(crate) trait SpanProvider<T> {
373    fn get_span(&self, handle: Handle<T>) -> Span;
374    fn get_span_context(&self, handle: Handle<T>) -> SpanContext {
375        match self.get_span(handle) {
376            x if !x.is_defined() => (Default::default(), "".to_string()),
377            known => (
378                known,
379                format!("{} {:?}", core::any::type_name::<T>(), handle),
380            ),
381        }
382    }
383}
384
385impl<T> SpanProvider<T> for Arena<T> {
386    fn get_span(&self, handle: Handle<T>) -> Span {
387        self.get_span(handle)
388    }
389}
390
391impl<T> SpanProvider<T> for UniqueArena<T> {
392    fn get_span(&self, handle: Handle<T>) -> Span {
393        self.get_span(handle)
394    }
395}
396
397/// Convenience trait for [`Result`], adding a [`MapErrWithSpan::map_err_inner`]
398/// mapping to [`WithSpan::and_then`].
399pub(crate) trait MapErrWithSpan<E, E2>: Sized {
400    /// The returned output type.
401    type Output: Sized;
402
403    fn map_err_inner<F, E3>(self, func: F) -> Self::Output
404    where
405        F: FnOnce(E) -> WithSpan<E3>,
406        E2: From<E3>;
407}
408
409impl<T, E, E2> MapErrWithSpan<E, E2> for Result<T, WithSpan<E>> {
410    type Output = Result<T, WithSpan<E2>>;
411
412    fn map_err_inner<F, E3>(self, func: F) -> Result<T, WithSpan<E2>>
413    where
414        F: FnOnce(E) -> WithSpan<E3>,
415        E2: From<E3>,
416    {
417        self.map_err(|e| e.and_then(func).into_other::<E2>())
418    }
419}
420
421#[test]
422fn span_location() {
423    let source = "12\n45\n\n89\n";
424    assert_eq!(
425        Span { start: 0, end: 1 }.location(source),
426        SourceLocation {
427            line_number: 1,
428            line_position: 1,
429            offset: 0,
430            length: 1
431        }
432    );
433    assert_eq!(
434        Span { start: 1, end: 2 }.location(source),
435        SourceLocation {
436            line_number: 1,
437            line_position: 2,
438            offset: 1,
439            length: 1
440        }
441    );
442    assert_eq!(
443        Span { start: 2, end: 3 }.location(source),
444        SourceLocation {
445            line_number: 1,
446            line_position: 3,
447            offset: 2,
448            length: 1
449        }
450    );
451    assert_eq!(
452        Span { start: 3, end: 5 }.location(source),
453        SourceLocation {
454            line_number: 2,
455            line_position: 1,
456            offset: 3,
457            length: 2
458        }
459    );
460    assert_eq!(
461        Span { start: 4, end: 6 }.location(source),
462        SourceLocation {
463            line_number: 2,
464            line_position: 2,
465            offset: 4,
466            length: 2
467        }
468    );
469    assert_eq!(
470        Span { start: 5, end: 6 }.location(source),
471        SourceLocation {
472            line_number: 2,
473            line_position: 3,
474            offset: 5,
475            length: 1
476        }
477    );
478    assert_eq!(
479        Span { start: 6, end: 7 }.location(source),
480        SourceLocation {
481            line_number: 3,
482            line_position: 1,
483            offset: 6,
484            length: 1
485        }
486    );
487    assert_eq!(
488        Span { start: 7, end: 8 }.location(source),
489        SourceLocation {
490            line_number: 4,
491            line_position: 1,
492            offset: 7,
493            length: 1
494        }
495    );
496    assert_eq!(
497        Span { start: 8, end: 9 }.location(source),
498        SourceLocation {
499            line_number: 4,
500            line_position: 2,
501            offset: 8,
502            length: 1
503        }
504    );
505    assert_eq!(
506        Span { start: 9, end: 10 }.location(source),
507        SourceLocation {
508            line_number: 4,
509            line_position: 3,
510            offset: 9,
511            length: 1
512        }
513    );
514    assert_eq!(
515        Span { start: 10, end: 11 }.location(source),
516        SourceLocation {
517            line_number: 5,
518            line_position: 1,
519            offset: 10,
520            length: 1
521        }
522    );
523}
naga/span.rs

naga/
span.rs
