Struct ScriptSnippet

pub struct ScriptSnippet<'a> { /* private fields */ }

A drawing object that renders the source code text of a ScriptModule with syntax highlighting and annotated source code ranges.

The intended use of this object is printing script source code to the terminal.

   ╭──╢ ‹doctest›.‹my_module.adastra› ╟────────────────────────────────────────╮
 1 │                                                                           │
 2 │     let foo = 10;                                                         │
   │         ╰╴ Annotation text.                                               │
 3 │     let bar = foo + 20;                                                   │
 4 │                                                                           │
   ╰───────────────────────────────────────────────────────────────────────────╯

There are several crate API functions that create this object, such as ModuleText::snippet and ModuleDiagnostics::highlight.

The Display implementation of this object performs the actual snippet rendering. For example, you can print the snippet to the terminal using the println macro: println!("{my_snippet}")

Implementations

impl<'a> ScriptSnippet<'a>

pub fn set_config(&mut self, config: ScriptSnippetConfig) -> &mut Self

Sets the configuration for snippet drawing features.

See ScriptSnippetConfig for details.

pub fn set_caption(&mut self, caption: impl AsRef<str>) -> &mut Self

Sets the caption of the printed content.

The caption string will be printed in the header of the snippet. By default, the caption is an empty string, and in this case, the renderer does not include a custom caption in the header.

The caption parameter must be a single-line string. Any additional caption lines (separated by the \n character) will be ignored.

pub fn set_summary(&mut self, summary: impl AsRef<str>) -> &mut Self

Sets the footer summary text of the printed content.

The summary string will be printed below the source code. By default, the summary is an empty string, and in this case, the renderer does not print any footer text.

Unlike the caption and annotation text, the summary text can have multiple lines.

pub fn annotate( &mut self, span: impl ToSpan, priority: AnnotationPriority, message: impl AsRef<str>, ) -> &mut Self

Adds an annotation to the source code.

The span argument specifies the source code range intended for annotation. You can use a 10..20 absolute Unicode character range, the line-column range Position::new(10, 3)..Position::new(12, 4), or the [ScriptOrigin] instance. The span argument must represent a valid value (e.g., 20..10 is not a valid range because the upper bound is less than the lower bound). Otherwise, the annotation will be silently ignored.

The priority argument specifies the annotation priority. The snippet interface supports the following priority types:

• AnnotationPriority::Default: A default annotation. The spanned text will be simply inverted (e.g., white text on a black background).
• AnnotationPriority::Primary: The spanned text will be inverted with a red background.
• AnnotationPriority::Secondary: The spanned text will be inverted with a blue background.
• AnnotationPriority::Note: The spanned text will be inverted with a yellow background.

The message argument specifies the text that should label the spanned range. The message should be a single-line string. Any additional message lines (separated by the \n character) will be ignored.

You can leave the message as an empty string. In this case, the renderer will not label the spanned text.

Note that if the ScriptSnippet does not have any annotations, the object will render the entire source code. Otherwise, the renderer will output only the annotated lines plus a few lines of surrounding context.

Trait Implementations

impl<'a> Display for ScriptSnippet<'a>

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<S: AsRef<str>> From<S> for ScriptSnippet<'static>

fn from(string: S) -> Self

Converts to this type from the input type.