Repository files navigation

ℹ️ This crate wassuperceded bycargo-expand, which added support for all the features that were missingwhen we started to work on cargo-inspect. Thanks all for your feedback and support.

There are only two ways to live your life.
One is as though nothing is a miracle. The other is as though everything is amiracle. -- Albert Einstein

You need Rust nightly andrustfmt to get started.
You can install those viarustup:

rustup install nightlyrustup component add rustfmt

All set? Let's get cracking!

cargo install cargo-inspect

Call it on any Rust file:

cargo inspect main.rs

If you don't specify a file, the current crate will be analyzed instead.

cargo inspect

Depending on the size of the crate, this might take a while.
Please be patient.

It can also compare two file outputs! Try this:

cargo inspect --diff examples/range.rs,examples/range_inclusive.rs --plain

USAGE:    cargo inspect [FLAGS] [OPTIONS] [INPUT_FILE]FLAGS:    -h, --help            Prints help information        --list-themes            Should we list all pretty printer themes?        --plain            Don't highlight output    -V, --version            Prints version information    -v, --verbose            Print the original code as a comment above the desugared codeOPTIONS:        --theme <THEME>            Specify a theme override for the pretty printer        --diff <files>            Diff input files        --format <format>            Override for the format that gets outputted when the `unpretty` mode is set to `flowgraph` [default: svg]        --unpretty <unpretty>            rustc "unpretty" parameters            *Note*: For `--unpretty=flowgraph=[symbol]` you need to have `dot` on your PATH. [default: hir]ARGS:    <INPUT_FILE>            Input file

Rust allows for a lot of syntactic sugar, that makes it a pleasure to write. Itis sometimes hard, however, to look behind the curtain and see what the compileris really doing with our code.

To quote @tshepang, "It is good to know what these conveniences are, to avoidbeing mystified by what's going on under the hood... the less magical thinkingwe have of the world, the better."

• lifetime elisions
• type inference
• syntactic sugar
• implicit dereferencing
• type coercions
• hidden code (e.g. the prelude)

I was always interested in how programming languages work in the background, howmy code was unrolled to make the compiler backend easier to maintain.

The goal is to make the compiler more approachable for mere mortals.
Mystery! Exploration! Discovery!

Read more on the background ofcargo-inspecton my blog.

Consider the following code snippet:

fnmain(){ifletSome(x) =Some(1){// Do something with x}}

When you compile it, the first thing Rust does is desugar it. To see what thecode looks like after this step, run

cargo inspect examples/if_let.rs

This produces the following output:

You can see that theif let was desugared into amatch statement.

To change the colorscheme, trycargo-inspect --list-themes, e.g.

cargo inspect examples/if_let.rs --theme GitHub

Oh, and if you havegraphviz installed, you can also print a pretty flowgraph from your code:

cargo inspect --unpretty=flowgraph=main examples/if_let.rs

Please find more examples in theexamples folder. You can also contributemore.

The best things in the world are assembled from simple building blocks. Thistool stands on the shoulders of giants. To work its magic, it runs the followingcommands:

1. rustc -Zinspect=hir, for retrieving the HIR.
2. rustfmt, for formatting the output.
3. prettyprint, for syntax-highlighting,which is just a wrapper around the awesomesyntectandbat crates.

This is a young project, which has downsides and upsides.

• Everything is in flux and things can break at any time. 😫
• There's plenty of opportunity to shape and form the project. 😊

Thus, become a contributor today!

As of now, this is a very fragile tool. If it fails, itmight will producehorrible output. You have been warned. That said, it won't eat your code, ofcourse. 😊

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE orhttp://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT orhttp://opensource.org/licenses/MIT)

at your option.

Magnifying glass designed byRawpixel.com