Skip to content

Commit 2ef961e

Browse files
committed
move to subsection
1 parent b95f349 commit 2ef961e

File tree

2 files changed

+37
-36
lines changed

2 files changed

+37
-36
lines changed

src/diag.md

+37
Original file line numberDiff line numberDiff line change
@@ -305,3 +305,40 @@ an appropriate mapping to the body of [`Lint::from_parser_lint_id`][fplid].
305305

306306
[`BufferedEarlyLintId`]: https://doc.rust-lang.org/nightly/nightly-rustc/syntax/early_buffered_lints/enum.BufferedEarlyLintId.html
307307
[fplid]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/lint/struct.Lint.html#method.from_parser_lint_id
308+
309+
## JSON diagnostic output
310+
311+
The compiler accepts an `--error-format json` flag to output
312+
diagnostics as JSON objects (for the benefit of tools such as `cargo
313+
fix` or the RLS). It looks like this—
314+
315+
```console
316+
$ rustc json_error_demo.rs --error-format json
317+
{"message":"cannot add `&str` to `{integer}`","code":{"code":"E0277","explanation":"\nYou tried to use a type which doesn't implement some trait in a place which\nexpected that trait. Erroneous code example:\n\n```compile_fail,E0277\n// here we declare the Foo trait with a bar method\ntrait Foo {\n fn bar(&self);\n}\n\n// we now declare a function which takes an object implementing the Foo trait\nfn some_func<T: Foo>(foo: T) {\n foo.bar();\n}\n\nfn main() {\n // we now call the method with the i32 type, which doesn't implement\n // the Foo trait\n some_func(5i32); // error: the trait bound `i32 : Foo` is not satisfied\n}\n```\n\nIn order to fix this error, verify that the type you're using does implement\nthe trait. Example:\n\n```\ntrait Foo {\n fn bar(&self);\n}\n\nfn some_func<T: Foo>(foo: T) {\n foo.bar(); // we can now use this method since i32 implements the\n // Foo trait\n}\n\n// we implement the trait on the i32 type\nimpl Foo for i32 {\n fn bar(&self) {}\n}\n\nfn main() {\n some_func(5i32); // ok!\n}\n```\n\nOr in a generic context, an erroneous code example would look like:\n\n```compile_fail,E0277\nfn some_func<T>(foo: T) {\n println!(\"{:?}\", foo); // error: the trait `core::fmt::Debug` is not\n // implemented for the type `T`\n}\n\nfn main() {\n // We now call the method with the i32 type,\n // which *does* implement the Debug trait.\n some_func(5i32);\n}\n```\n\nNote that the error here is in the definition of the generic function: Although\nwe only call it with a parameter that does implement `Debug`, the compiler\nstill rejects the function: It must work with all possible input types. In\norder to make this example compile, we need to restrict the generic type we're\naccepting:\n\n```\nuse std::fmt;\n\n// Restrict the input type to types that implement Debug.\nfn some_func<T: fmt::Debug>(foo: T) {\n println!(\"{:?}\", foo);\n}\n\nfn main() {\n // Calling the method is still fine, as i32 implements Debug.\n some_func(5i32);\n\n // This would fail to compile now:\n // struct WithoutDebug;\n // some_func(WithoutDebug);\n}\n```\n\nRust only looks at the signature of the called function, as such it must\nalready specify all requirements that will be used for every type parameter.\n"},"level":"error","spans":[{"file_name":"json_error_demo.rs","byte_start":50,"byte_end":51,"line_start":4,"line_end":4,"column_start":7,"column_end":8,"is_primary":true,"text":[{"text":" a + b","highlight_start":7,"highlight_end":8}],"label":"no implementation for `{integer} + &str`","suggested_replacement":null,"suggestion_applicability":null,"expansion":null}],"children":[{"message":"the trait `std::ops::Add<&str>` is not implemented for `{integer}`","code":null,"level":"help","spans":[],"children":[],"rendered":null}],"rendered":"error[E0277]: cannot add `&str` to `{integer}`\n --> json_error_demo.rs:4:7\n |\n4 | a + b\n | ^ no implementation for `{integer} + &str`\n |\n = help: the trait `std::ops::Add<&str>` is not implemented for `{integer}`\n\n"}
318+
{"message":"aborting due to previous error","code":null,"level":"error","spans":[],"children":[],"rendered":"error: aborting due to previous error\n\n"}
319+
{"message":"For more information about this error, try `rustc --explain E0277`.","code":null,"level":"","spans":[],"children":[],"rendered":"For more information about this error, try `rustc --explain E0277`.\n"}
320+
```
321+
322+
Note that the output is a series of lines, each of which is a JSON
323+
object, but the series of lines taken together is, unfortunately, not
324+
valid JSON, thwarting tools and tricks (such as [piping to `python3 -m
325+
json.tool`](https://docs.python.org/3/library/json.html#module-json.tool))
326+
that require such. (One speculates that this was intentional for LSP
327+
performance purposes, so that each line/object can be sent to RLS as
328+
it is flushed?)
329+
330+
Also note the "rendered" field, which contains the "human" output as a
331+
string; this was introduced so that UI tests could both make use of
332+
the structured JSON and see the "human" output (well, _sans_ colors)
333+
without having to compile everything twice.
334+
335+
The JSON emitter currently lives in libsyntax/json.rs. (But arguably
336+
it should live in librustc_errors along with the "human" emitter? It's
337+
not obvious to the present author why it wasn't moved from libsyntax
338+
to librustc_errors at the same [time the "human" emitter was
339+
moved](https://github.com/rust-lang/rust/commit/6ae3502134).)
340+
341+
The JSON emitter defines [its own `Diagnostic`
342+
struct](https://github.com/rust-lang/rust/blob/b2c6b8c29f13f8d1f242da89e587960b95337819/src/libsyntax/json.rs#L85-L99)
343+
(and sub-structs) for the JSON serialization. Don't confuse this with
344+
[`errors::Diagnostic`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/struct.Diagnostic.html)!

src/diag/json-format.md

-36
Original file line numberDiff line numberDiff line change
@@ -1,36 +0,0 @@
1-
# JSON diagnostic output
2-
3-
The compiler accepts an `--error-format json` flag to output
4-
diagnostics as JSON objects (for the benefit of tools such as `cargo
5-
fix` or the RLS). It looks like this—
6-
7-
```ignore
8-
$ rustc json_error_demo.rs --error-format json
9-
{"message":"cannot add `&str` to `{integer}`","code":{"code":"E0277","explanation":"\nYou tried to use a type which doesn't implement some trait in a place which\nexpected that trait. Erroneous code example:\n\n```compile_fail,E0277\n// here we declare the Foo trait with a bar method\ntrait Foo {\n fn bar(&self);\n}\n\n// we now declare a function which takes an object implementing the Foo trait\nfn some_func<T: Foo>(foo: T) {\n foo.bar();\n}\n\nfn main() {\n // we now call the method with the i32 type, which doesn't implement\n // the Foo trait\n some_func(5i32); // error: the trait bound `i32 : Foo` is not satisfied\n}\n```\n\nIn order to fix this error, verify that the type you're using does implement\nthe trait. Example:\n\n```\ntrait Foo {\n fn bar(&self);\n}\n\nfn some_func<T: Foo>(foo: T) {\n foo.bar(); // we can now use this method since i32 implements the\n // Foo trait\n}\n\n// we implement the trait on the i32 type\nimpl Foo for i32 {\n fn bar(&self) {}\n}\n\nfn main() {\n some_func(5i32); // ok!\n}\n```\n\nOr in a generic context, an erroneous code example would look like:\n\n```compile_fail,E0277\nfn some_func<T>(foo: T) {\n println!(\"{:?}\", foo); // error: the trait `core::fmt::Debug` is not\n // implemented for the type `T`\n}\n\nfn main() {\n // We now call the method with the i32 type,\n // which *does* implement the Debug trait.\n some_func(5i32);\n}\n```\n\nNote that the error here is in the definition of the generic function: Although\nwe only call it with a parameter that does implement `Debug`, the compiler\nstill rejects the function: It must work with all possible input types. In\norder to make this example compile, we need to restrict the generic type we're\naccepting:\n\n```\nuse std::fmt;\n\n// Restrict the input type to types that implement Debug.\nfn some_func<T: fmt::Debug>(foo: T) {\n println!(\"{:?}\", foo);\n}\n\nfn main() {\n // Calling the method is still fine, as i32 implements Debug.\n some_func(5i32);\n\n // This would fail to compile now:\n // struct WithoutDebug;\n // some_func(WithoutDebug);\n}\n```\n\nRust only looks at the signature of the called function, as such it must\nalready specify all requirements that will be used for every type parameter.\n"},"level":"error","spans":[{"file_name":"json_error_demo.rs","byte_start":50,"byte_end":51,"line_start":4,"line_end":4,"column_start":7,"column_end":8,"is_primary":true,"text":[{"text":" a + b","highlight_start":7,"highlight_end":8}],"label":"no implementation for `{integer} + &str`","suggested_replacement":null,"suggestion_applicability":null,"expansion":null}],"children":[{"message":"the trait `std::ops::Add<&str>` is not implemented for `{integer}`","code":null,"level":"help","spans":[],"children":[],"rendered":null}],"rendered":"error[E0277]: cannot add `&str` to `{integer}`\n --> json_error_demo.rs:4:7\n |\n4 | a + b\n | ^ no implementation for `{integer} + &str`\n |\n = help: the trait `std::ops::Add<&str>` is not implemented for `{integer}`\n\n"}
10-
{"message":"aborting due to previous error","code":null,"level":"error","spans":[],"children":[],"rendered":"error: aborting due to previous error\n\n"}
11-
{"message":"For more information about this error, try `rustc --explain E0277`.","code":null,"level":"","spans":[],"children":[],"rendered":"For more information about this error, try `rustc --explain E0277`.\n"}
12-
```
13-
14-
Note that the output is a series of lines, each of which is a JSON
15-
object, but the series of lines taken together is, unfortunately, not
16-
valid JSON, thwarting tools and tricks (such as [piping to `python3 -m
17-
json.tool`](https://docs.python.org/3/library/json.html#module-json.tool))
18-
that require such. (One speculates that this was intentional for LSP
19-
performance purposes, so that each line/object can be sent to RLS as
20-
it is flushed?)
21-
22-
Also note the "rendered" field, which contains the "human" output as a
23-
string; this was introduced so that UI tests could both make use of
24-
the structured JSON and see the "human" output (well, _sans_ colors)
25-
without having to compile everything twice.
26-
27-
The JSON emitter currently lives in libsyntax/json.rs. (But arguably
28-
it should live in librustc_errors along with the "human" emitter? It's
29-
not obvious to the present author why it wasn't moved from libsyntax
30-
to librustc_errors at the same [time the "human" emitter was
31-
moved](https://github.com/rust-lang/rust/commit/6ae3502134).)
32-
33-
The JSON emitter defines [its own `Diagnostic`
34-
struct](https://github.com/rust-lang/rust/blob/b2c6b8c29f13f8d1f242da89e587960b95337819/src/libsyntax/json.rs#L85-L99)
35-
(and sub-structs) for the JSON serialization. Don't confuse this with
36-
[`errors::Diagnostic`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/struct.Diagnostic.html)!

0 commit comments

Comments
 (0)