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::{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    pub fn emit_to_stderr(&self, source: &str)
277    where
278        E: Error,
279    {
280        self.emit_to_stderr_with_path(source, "wgsl")
281    }
282
283    /// Emits a summary of the error to standard error stream.
284    pub fn emit_to_stderr_with_path(&self, source: &str, path: &str)
285    where
286        E: Error,
287    {
288        use codespan_reporting::term::termcolor::{ColorChoice, StandardStream};
289        use codespan_reporting::{files, term};
290
291        let files = files::SimpleFile::new(path, source);
292        let config = term::Config::default();
293        let writer = StandardStream::stderr(ColorChoice::Auto);
294        term::emit(&mut writer.lock(), &config, &files, &self.diagnostic())
295            .expect("cannot write error");
296    }
297
298    /// Emits a summary of the error to a string.
299    pub fn emit_to_string(&self, source: &str) -> String
300    where
301        E: Error,
302    {
303        self.emit_to_string_with_path(source, "wgsl")
304    }
305
306    /// Emits a summary of the error to a string.
307    pub fn emit_to_string_with_path(&self, source: &str, path: &str) -> String
308    where
309        E: Error,
310    {
311        use codespan_reporting::term::termcolor::NoColor;
312        use codespan_reporting::{files, term};
313
314        let files = files::SimpleFile::new(path, source);
315        let config = term::Config::default();
316        let mut writer = NoColor::new(Vec::new());
317        term::emit(&mut writer, &config, &files, &self.diagnostic()).expect("cannot write error");
318        String::from_utf8(writer.into_inner()).unwrap()
319    }
320}
321
322/// Convenience trait for [`Error`] to be able to apply spans to anything.
323pub(crate) trait AddSpan: Sized {
324    /// The returned output type.
325    type Output;
326
327    /// See [`WithSpan::new`].
328    fn with_span(self) -> Self::Output;
329    /// See [`WithSpan::with_span`].
330    fn with_span_static(self, span: Span, description: &'static str) -> Self::Output;
331    /// See [`WithSpan::with_context`].
332    fn with_span_context(self, span_context: SpanContext) -> Self::Output;
333    /// See [`WithSpan::with_handle`].
334    fn with_span_handle<T, A: SpanProvider<T>>(self, handle: Handle<T>, arena: &A) -> Self::Output;
335}
336
337impl<E> AddSpan for E {
338    type Output = WithSpan<Self>;
339
340    fn with_span(self) -> WithSpan<Self> {
341        WithSpan::new(self)
342    }
343
344    fn with_span_static(self, span: Span, description: &'static str) -> WithSpan<Self> {
345        WithSpan::new(self).with_span(span, description)
346    }
347
348    fn with_span_context(self, span_context: SpanContext) -> WithSpan<Self> {
349        WithSpan::new(self).with_context(span_context)
350    }
351
352    fn with_span_handle<T, A: SpanProvider<T>>(
353        self,
354        handle: Handle<T>,
355        arena: &A,
356    ) -> WithSpan<Self> {
357        WithSpan::new(self).with_handle(handle, arena)
358    }
359}
360
361/// Trait abstracting over getting a span from an [`Arena`] or a [`UniqueArena`].
362pub(crate) trait SpanProvider<T> {
363    fn get_span(&self, handle: Handle<T>) -> Span;
364    fn get_span_context(&self, handle: Handle<T>) -> SpanContext {
365        match self.get_span(handle) {
366            x if !x.is_defined() => (Default::default(), "".to_string()),
367            known => (
368                known,
369                format!("{} {:?}", core::any::type_name::<T>(), handle),
370            ),
371        }
372    }
373}
374
375impl<T> SpanProvider<T> for Arena<T> {
376    fn get_span(&self, handle: Handle<T>) -> Span {
377        self.get_span(handle)
378    }
379}
380
381impl<T> SpanProvider<T> for UniqueArena<T> {
382    fn get_span(&self, handle: Handle<T>) -> Span {
383        self.get_span(handle)
384    }
385}
386
387/// Convenience trait for [`Result`], adding a [`MapErrWithSpan::map_err_inner`]
388/// mapping to [`WithSpan::and_then`].
389pub(crate) trait MapErrWithSpan<E, E2>: Sized {
390    /// The returned output type.
391    type Output: Sized;
392
393    fn map_err_inner<F, E3>(self, func: F) -> Self::Output
394    where
395        F: FnOnce(E) -> WithSpan<E3>,
396        E2: From<E3>;
397}
398
399impl<T, E, E2> MapErrWithSpan<E, E2> for Result<T, WithSpan<E>> {
400    type Output = Result<T, WithSpan<E2>>;
401
402    fn map_err_inner<F, E3>(self, func: F) -> Result<T, WithSpan<E2>>
403    where
404        F: FnOnce(E) -> WithSpan<E3>,
405        E2: From<E3>,
406    {
407        self.map_err(|e| e.and_then(func).into_other::<E2>())
408    }
409}
410
411#[test]
412fn span_location() {
413    let source = "12\n45\n\n89\n";
414    assert_eq!(
415        Span { start: 0, end: 1 }.location(source),
416        SourceLocation {
417            line_number: 1,
418            line_position: 1,
419            offset: 0,
420            length: 1
421        }
422    );
423    assert_eq!(
424        Span { start: 1, end: 2 }.location(source),
425        SourceLocation {
426            line_number: 1,
427            line_position: 2,
428            offset: 1,
429            length: 1
430        }
431    );
432    assert_eq!(
433        Span { start: 2, end: 3 }.location(source),
434        SourceLocation {
435            line_number: 1,
436            line_position: 3,
437            offset: 2,
438            length: 1
439        }
440    );
441    assert_eq!(
442        Span { start: 3, end: 5 }.location(source),
443        SourceLocation {
444            line_number: 2,
445            line_position: 1,
446            offset: 3,
447            length: 2
448        }
449    );
450    assert_eq!(
451        Span { start: 4, end: 6 }.location(source),
452        SourceLocation {
453            line_number: 2,
454            line_position: 2,
455            offset: 4,
456            length: 2
457        }
458    );
459    assert_eq!(
460        Span { start: 5, end: 6 }.location(source),
461        SourceLocation {
462            line_number: 2,
463            line_position: 3,
464            offset: 5,
465            length: 1
466        }
467    );
468    assert_eq!(
469        Span { start: 6, end: 7 }.location(source),
470        SourceLocation {
471            line_number: 3,
472            line_position: 1,
473            offset: 6,
474            length: 1
475        }
476    );
477    assert_eq!(
478        Span { start: 7, end: 8 }.location(source),
479        SourceLocation {
480            line_number: 4,
481            line_position: 1,
482            offset: 7,
483            length: 1
484        }
485    );
486    assert_eq!(
487        Span { start: 8, end: 9 }.location(source),
488        SourceLocation {
489            line_number: 4,
490            line_position: 2,
491            offset: 8,
492            length: 1
493        }
494    );
495    assert_eq!(
496        Span { start: 9, end: 10 }.location(source),
497        SourceLocation {
498            line_number: 4,
499            line_position: 3,
500            offset: 9,
501            length: 1
502        }
503    );
504    assert_eq!(
505        Span { start: 10, end: 11 }.location(source),
506        SourceLocation {
507            line_number: 5,
508            line_position: 1,
509            offset: 10,
510            length: 1
511        }
512    );
513}
naga/span.rs

naga/
span.rs
