codespan_preprocessed/lib.rs
1//! # Codemap for Preprocessed File
2//!
3//! This is an extension for the very useful crate `codespan_reporting`
4//! to deal with preprocessed file through the well-known`m4` or `cpp`.
5//!
6//! Using such a preprocessor allows, among a lost of things, the
7//! inclusion of many files which are identified in the bytes sequence
8//! with preprecessor directive as:
9//!```text
10//! #line 42 "/my/preprocessed/file"
11//!```
12//! This directive breaks the location of the source and so
13//! should be correctly processed to make correct location
14//! for error reporting.
15//!
16//! This is the purpose of this crate: taking a preprocessor
17//! output and managing the different underlying locations
18//! inside it.
19//!
20//! # Example
21//!
22//!```
23//! use codespan_preprocessed::reporting::Diagnostic;
24//! use codespan_preprocessed::PreprocessedFile;
25//!
26//! let contents = PreprocessedFile::new(
27//! unindent::unindent(
28//! r#"
29//! #line 1 "top_file"
30//! a first statement;
31//! another one
32//!
33//! #line 1 "included_file"
34//! continue...
35//!
36//! #line 5
37//! another line
38//! the last one
39//! "#,
40//! ),
41//! );
42//!
43//! // build a diagnostic for reporting
44//! let diagnostic = Diagnostic::note()
45//! .with_message("this is just an example")
46//! .with_primary_label(113..117, "do you see that ?")
47//! .with_secondary_label(21..26, "is it related to this ?");
48//!```
49//!
50//! ### Reporting a diagnostic
51//! The first way to make reporting is based of `codespan_reporting` (see documentation for more details).
52//!```
53//! use codespan_reporting::term;
54//! use codespan_reporting::term::termcolor::{ColorChoice, StandardStream};
55//! # use codespan_preprocessed::reporting::*;
56//! # use codespan_preprocessed::PreprocessedFile;
57//!
58//! # fn main()
59//! # {
60//! # let contents = PreprocessedFile::new("");
61//! # let diagnostic = Diagnostic::note();
62//! let writer = StandardStream::stderr(ColorChoice::Always);
63//! let config = codespan_reporting::term::Config::default();
64//! term::emit_to_write_style(&mut writer.lock(), &config, &contents, &diagnostic.to_diagnostic(&contents));
65//! # }
66//!```
67//! ### Easy reporting (alternative)
68//! This crate provides an easier way to report diagnostic based on
69//! preprocessed file.
70//! ```
71//! # use codespan_reporting::term;
72//! # use codespan_reporting::term::termcolor::{ColorChoice, StandardStream};
73//! use codespan_preprocessed::reporting::{Diagnostic,EasyReport,EasyReporting};
74//! # use codespan_preprocessed::PreprocessedFile;
75//!
76//! # fn main()
77//! # {
78//! # let contents = PreprocessedFile::new("");
79//! # let diagnostic = Diagnostic::note();
80//! let report = EasyReporting::new(&contents);
81//! report.emit(diagnostic);
82//! # }
83//! ```
84//! ### Output
85//! The both previous codes will produce:
86//! ```text
87//! note: this is just an example
88//! ┌─ included_file:6:5
89//! │
90//! 6 │ the last one
91//! │ ^^^^ do you see that ?
92//! │
93//! ┌─ top_file:1:3
94//! │
95//! 1 │ a first statement;
96//! │ ----- is it related to this ?
97//! ```
98mod codemap;
99mod easyloc;
100pub mod reporting;
101
102pub use codemap::EasyLocation;
103pub use codemap::PreprocessedFile;
104pub use easyloc::{EasyLocated, EasyLocator};