<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>src/tools/rustfmt/Contributing.md - fork/rust @ master</title>
<meta name="description" content="src/tools/rustfmt/Contributing.md in fork/rust at master.">
<meta property="og:title" content="src/tools/rustfmt/Contributing.md - fork/rust @ master">
<meta property="og:description" content="src/tools/rustfmt/Contributing.md in fork/rust at master.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="master" data-tip="3bcad65fbf67b6edf87c949531fbc13435882e6b">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/rust</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/rust</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">bors</span><span class="commit-message" data-commit="3bcad65fbf67b6edf87c949531fbc13435882e6b">Auto merge of #103046 - JanBeh:PR_clarify_cmp_terminology, r=workingjubilee</span><span class="snapshot-sha sha" data-commit="3bcad65fbf67b6edf87c949531fbc13435882e6b">3bcad65fbf6</span><time datetime="2023-10-05T15:24:54+00:00" title="2023-10-05 15:24:54 +0000">2023-10-05</time></p>
<header class="topbar"><details class="switcher"><summary>master</summary><div class="menu"><strong>branches</strong><a class="current" href="/fork/rust/ref/master/">master</a><strong>tags</strong><a href="/fork/rust/ref/1.39.0/">1.39.0</a><a href="/fork/rust/ref/1.40.0/">1.40.0</a><a href="/fork/rust/ref/1.41.0/">1.41.0</a><a href="/fork/rust/ref/1.41.1/">1.41.1</a><a href="/fork/rust/ref/1.42.0/">1.42.0</a><a href="/fork/rust/ref/1.43.0/">1.43.0</a><a href="/fork/rust/ref/1.43.1/">1.43.1</a><a href="/fork/rust/ref/1.44.0/">1.44.0</a><a class="all" href="/fork/rust/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/rust/">rust</a> / <a href="/fork/rust/ref/master/tree/src/">src</a> / <a href="/fork/rust/ref/master/tree/src/tools/">tools</a> / <a href="/fork/rust/ref/master/tree/src/tools/rustfmt/">rustfmt</a> / <span class="cur">Contributing.md</span></nav>
<span class="view-stats"><span>12.8 KiB</span><span>261 lines</span></span><span class="actions"><a class="raw" href="/fork/rust/raw/b986a887c92ff359cc3ea27193633cefbe71104e/src/tools/rustfmt/Contributing.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1>Contributing</h1>
<p>There are many ways to contribute to Rustfmt. This document lays out what they
are and has information on how to get started. If you have any questions about
contributing or need help with anything, please ask in the WG-Rustfmt channel
on <a href="https://discordapp.com/invite/rust-lang">Discord</a>. Feel free to also ask questions
on issues, or file new issues specifically to get help.</p>
<p>All contributors are expected to follow our <a href="/fork/rust/ref/master/blob/src/tools/rustfmt/CODE_OF_CONDUCT.md">Code of
Conduct</a>.</p>
<h2>Test and file issues</h2>
<p>It would be really useful to have people use rustfmt on their projects and file
issues where it does something you don't expect.</p>
<h2>Create test cases</h2>
<p>Having a strong test suite for a tool like this is essential. It is very easy
to create regressions. Any tests you can add are very much appreciated.</p>
<p>The tests can be run with <code>cargo test</code>. This does a number of things:</p>
<ul>
<li>runs the unit tests for a number of internal functions;</li>
<li>makes sure that rustfmt run on every file in <code>./tests/source/</code> is equal to its
associated file in <code>./tests/target/</code>;</li>
<li>runs idempotence tests on the files in <code>./tests/target/</code>. These files should
not be changed by rustfmt;</li>
<li>checks that rustfmt's code is not changed by running on itself. This ensures
that the project bootstraps.</li>
</ul>
<p>Creating a test is as easy as creating a new file in <code>./tests/source/</code> and an
equally named one in <code>./tests/target/</code>. If it is only required that rustfmt
leaves a piece of code unformatted, it may suffice to only create a target file.</p>
<p>Whenever there's a discrepancy between the expected output when running tests, a
colourised diff will be printed so that the offending line(s) can quickly be
identified.</p>
<p>Without explicit settings, the tests will be run using rustfmt's default
configuration. It is possible to run a test using non-default settings in several
ways. Firstly, you can include configuration parameters in comments at the top
of the file. For example: to use 3 spaces per tab, start your test with
<code>// rustfmt-tab_spaces: 3</code>. Just remember that the comment is part of the input,
so include in both the source and target files! It is also possible to
explicitly specify the name of the expected output file in the target directory.
Use <code>// rustfmt-target: filename.rs</code> for this. You can also specify a custom
configuration by using the <code>rustfmt-config</code> directive. Rustfmt will then use
that toml file located in <code>./tests/config/</code> for its configuration. Including
<code>// rustfmt-config: small_tabs.toml</code> will run your test with the configuration
file found at <code>./tests/config/small_tabs.toml</code>. The final option is used when the
test source file contains no configuration parameter comments. In this case, the
test harness looks for a configuration file with the same filename as the test
file in the <code>./tests/config/</code> directory, so a test source file named <code>test-indent.rs</code>
would need a configuration file named <code>test-indent.toml</code> in that directory. As an
example, the <code>issue-1111.rs</code> test file is configured by the file
<code>./tests/config/issue-1111.toml</code>.</p>
<h2>Debugging</h2>
<p>Some <code>rewrite_*</code> methods use the <code>debug!</code> macro for printing useful information.
These messages can be printed by using the environment variable <code>RUSTFMT_LOG=rustfmt=DEBUG</code>.
These traces can be helpful in understanding which part of the code was used
and get a better grasp on the execution flow.</p>
<h2>Hack!</h2>
<p>Here are some <a href="https://github.com/rust-lang/rustfmt/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22">good starting issues</a>.</p>
<p>If you've found areas which need polish and don't have issues, please submit a
PR, don't feel there needs to be an issue.</p>
<h3>Guidelines</h3>
<p>Rustfmt bootstraps, that is part of its test suite is running itself on its
source code. So, basically, the only style guideline is that you must pass the
tests. That ensures that the Rustfmt source code adheres to our own conventions.</p>
<p>Talking of tests, if you add a new feature or fix a bug, please also add a test.
It's really easy, see above for details. Please run <code>cargo test</code> before
submitting a PR to ensure your patch passes all tests, it's pretty quick.</p>
<p>Rustfmt is post-1.0 and within major version releases we strive for backwards
compatibility (at least when using the default options). That means any code
which changes Rustfmt's output must be guarded by either an option or a version
check. The latter is implemented as an option called <code>option</code>. See the section on
<a href="#Configuration">configuration</a> below.</p>
<p>Please try to avoid leaving <code>TODO</code>s in the code. There are a few around, but I
wish there weren't. You can leave <code>FIXME</code>s, preferably with an issue number.</p>
<h3>Run Rustfmt from source code</h3>
<p>You may want to run a version of rustfmt from source code as part of a test or
hacking on the rustfmt codebase. It's strongly discouraged to install a version
of rustfmt from source. Instead, run it using <code>cargo run</code>, and <code>--manifest-path</code>.</p>
<pre>cargo run --bin cargo-fmt -- --manifest-path path/to/project/you/want2test/Cargo.toml
</pre>
<h3>Version-gate formatting changes</h3>
<p>A change that introduces a different code-formatting should be gated on the
<code>version</code> configuration. This is to ensure the formatting of the current major
release is preserved, while allowing fixes to be implemented for the next
release.</p>
<p>This is done by conditionally guarding the change like so:</p>
<pre class="language-rust"><a-k>if</a-k> config<a-p>.</a-p><a-f>version</a-f><a-p>()</a-p> == <a-t>Version</a-t><a-p>::</a-p><a-cr>One</a-cr> <a-p>{</a-p> <a-c>// if the current major release is 1.x</a-c>
    <a-c>// current formatting</a-c>
<a-p>}</a-p> <a-k>else</a-k> <a-p>{</a-p>
    <a-c>// new formatting</a-c>
<a-p>}</a-p></pre>
<p>This allows the user to apply the next formatting explicitly via the
configuration, while being stable by default.</p>
<p>When the next major release is done, the code block of the previous formatting
can be deleted, e.g., the first block in the example above when going from <code>1.x</code>
to <code>2.x</code>.</p>
<table><thead><tr><th>Note: Only formatting changes with default options need to be gated.</th></tr></thead><tbody>
</tbody></table>
<h3>A quick tour of Rustfmt</h3>
<p>Rustfmt is basically a pretty printer - that is, its mode of operation is to
take an AST (abstract syntax tree) and print it in a nice way (including staying
under the maximum permitted width for a line). In order to get that AST, we
first have to parse the source text, we use the Rust compiler's parser to do
that (see <a href="/fork/rust/ref/master/blob/src/tools/rustfmt/src/lib.rs">src/lib.rs</a>). We shy away from doing anything too fancy, such as
algebraic approaches to pretty printing, instead relying on an heuristic
approach, 'manually' crafting a string for each AST node. This results in quite
a lot of code, but it is relatively simple.</p>
<p>The AST is a tree view of source code. It carries all the semantic information
about the code, but not all of the syntax. In particular, we lose white space
and comments (although doc comments are preserved). Rustfmt uses a view of the
AST before macros are expanded, so there are still macro uses in the code. The
arguments to macros are not an AST, but raw tokens - this makes them harder to
format.</p>
<p>There are different nodes for every kind of item and expression in Rust. For
more details see the source code in the compiler -
<a href="https://github.com/rust-lang/rust/blob/master/compiler/rustc_ast/src/ast.rs">ast.rs</a> - and/or the
<a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/ast/index.html">docs</a>.</p>
<p>Many nodes in the AST (but not all, annoyingly) have a <code>Span</code>. A <code>Span</code> is a
range in the source code, it can easily be converted to a snippet of source
text. When the AST does not contain enough information for us, we rely heavily
on <code>Span</code>s. For example, we can look between spans to try and find comments, or
parse a snippet to see how the user wrote their source code.</p>
<p>The downside of using the AST is that we miss some information - primarily white
space and comments. White space is sometimes significant, although mostly we
want to ignore it and make our own. We strive to reproduce all comments, but
this is sometimes difficult. The crufty corners of Rustfmt are where we hack
around the absence of comments in the AST and try to recreate them as best we
can.</p>
<p>Our primary tool here is to look between spans for text we've missed. For
example, in a function call <code>foo(a, b)</code>, we have spans for <code>a</code> and <code>b</code>, in this
case, there is only a comma and a single space between the end of <code>a</code> and the
start of <code>b</code>, so there is nothing much to do. But if we look at
<code>foo(a /* a comment */, b)</code>, then between <code>a</code> and <code>b</code> we find the comment.</p>
<p>At a higher level, Rustfmt has machinery so that we account for text between
'top level' items. Then we can reproduce that text pretty much verbatim. We only
count spans we actually reformat, so if we can't format a span it is not missed
completely but is reproduced in the output without being formatted. This is
mostly handled in <a href="/fork/rust/ref/master/blob/src/tools/rustfmt/src/missed_spans.rs">src/missed_spans.rs</a>. See also <code>FmtVisitor::last_pos</code> in
<a href="/fork/rust/ref/master/blob/src/tools/rustfmt/src/visitor.rs">src/visitor.rs</a>.</p>
<h4>Some important elements</h4>
<p>At the highest level, Rustfmt uses a <code>Visitor</code> implementation called <code>FmtVisitor</code>
to walk the AST. This is in <a href="/fork/rust/ref/master/blob/src/tools/rustfmt/src/visitor.rs">src/visitor.rs</a>. This is really just used to walk
items, rather than the bodies of functions. We also cover macros and attributes
here. Most methods of the visitor call out to <code>Rewrite</code> implementations that
then walk their own children.</p>
<p>The <code>Rewrite</code> trait is defined in <a href="/fork/rust/ref/master/blob/src/tools/rustfmt/src/rewrite.rs">src/rewrite.rs</a>. It is implemented for many
things that can be rewritten, mostly AST nodes. It has a single function,
<code>rewrite</code>, which is called to rewrite <code>self</code> into an <code>Option&lt;String&gt;</code>. The
arguments are <code>width</code> which is the horizontal space we write into and <code>offset</code>
which is how much we are currently indented from the lhs of the page. We also
take a context which contains information used for parsing, the current block
indent, and a configuration (see below).</p>
<h5>Rewrite and Indent</h5>
<p>To understand the indents, consider</p>
<pre>impl Foo {
    fn foo(...) {
        bar(argument_one,
            baz());
    }
}
</pre>
<p>When formatting the <code>bar</code> call we will format the arguments in order, after the
first one we know we are working on multiple lines (imagine it is longer than
written). So, when we come to the second argument, the indent we pass to
<code>rewrite</code> is 12, which puts us under the first argument. The current block
indent (stored in the context) is 8. The former is used for visual indenting
(when objects are vertically aligned with some marker), the latter is used for
block indenting (when objects are tabbed in from the lhs). The width available
for <code>baz()</code> will be the maximum width, minus the space used for indenting, minus
the space used for the <code>);</code>. (Note that actual argument formatting does not
quite work like this, but it's close enough).</p>
<p>The <code>rewrite</code> function returns an <code>Option</code> - either we successfully rewrite and
return the rewritten string for the caller to use, or we fail to rewrite and
return <code>None</code>. This could be because Rustfmt encounters something it doesn't
know how to reformat, but more often it is because Rustfmt can't fit the item
into the required width. How to handle this is up to the caller. Often the
caller just gives up, ultimately relying on the missed spans system to paste in
the un-formatted source. A better solution (although not performed in many
places) is for the caller to shuffle around some of its other items to make
more width, then call the function again with more space.</p>
<p>Since it is common for callers to bail out when a callee fails, we often use a
<code>?</code> operator to make this pattern more succinct.</p>
<p>One way we might find out that we don't have enough space is when computing how much
space we have. Something like <code>available_space = budget - overhead</code>. Since
widths are unsized integers, this would cause underflow. Therefore we use
checked subtraction: <code>available_space = budget.checked_sub(overhead)?</code>.
<code>checked_sub</code> returns an <code>Option</code>, and if we would underflow <code>?</code> returns
<code>None</code>, otherwise, we proceed with the computed space.</p>
<h5>Rewrite of list-like expressions</h5>
<p>Much of the syntax in Rust is lists: lists of arguments, lists of fields, lists of
array elements, etc. We have some generic code to handle lists, including how to
space them in horizontal and vertical space, indentation, comments between
items, trailing separators, etc. However, since there are so many options, the
code is a bit complex. Look in <a href="/fork/rust/ref/master/blob/src/tools/rustfmt/src/lists.rs">src/lists.rs</a>. <code>write_list</code> is the key function,
and <code>ListFormatting</code> the key structure for configuration. You'll need to make a
<code>ListItems</code> for input, this is usually done using <code>itemize_list</code>.</p>
<h5>Configuration</h5>
<p>Rustfmt strives to be highly configurable. Often the first part of a patch is
creating a configuration option for the feature you are implementing. All
handling of configuration options is done in <a href="/fork/rust/ref/master/blob/src/tools/rustfmt/src/config/mod.rs">src/config/mod.rs</a>. Look for the
<code>create_config!</code> macro at the end of the file for all the options. The rest of
the file defines a bunch of enums used for options, and the machinery to produce
the config struct and parse a config file, etc. Checking an option is done by
accessing the correct field on the config struct, e.g., <code>config.max_width()</code>. Most
functions have a <code>Config</code>, or one can be accessed via a visitor or context of
some kind.</p>
</section><div class="code-panel"><pre class="code src" data-hl="src/tools/rustfmt/Contributing.md"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"># Contributing</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">There are many ways to contribute to Rustfmt. This document lays out what they</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text">are and has information on how to get started. If you have any questions about</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">contributing or need help with anything, please ask in the WG-Rustfmt channel</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text">on [Discord](https://discordapp.com/invite/rust-lang). Feel free to also ask questions</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text">on issues, or file new issues specifically to get help.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">All contributors are expected to follow our [Code of</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text">Conduct](CODE_OF_CONDUCT.md).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text">## Test and file issues</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text">It would be really useful to have people use rustfmt on their projects and file</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text">issues where it does something you don't expect.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text">## Create test cases</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text">Having a strong test suite for a tool like this is essential. It is very easy</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text">to create regressions. Any tests you can add are very much appreciated.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text">The tests can be run with `cargo test`. This does a number of things:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text">* runs the unit tests for a number of internal functions;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text">* makes sure that rustfmt run on every file in `./tests/source/` is equal to its</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text">  associated file in `./tests/target/`;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text">* runs idempotence tests on the files in `./tests/target/`. These files should</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text">  not be changed by rustfmt;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text">* checks that rustfmt's code is not changed by running on itself. This ensures</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text">  that the project bootstraps.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text">Creating a test is as easy as creating a new file in `./tests/source/` and an</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text">equally named one in `./tests/target/`. If it is only required that rustfmt</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text">leaves a piece of code unformatted, it may suffice to only create a target file.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text">Whenever there's a discrepancy between the expected output when running tests, a</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text">colourised diff will be printed so that the offending line(s) can quickly be</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text">identified.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text">Without explicit settings, the tests will be run using rustfmt's default</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text">configuration. It is possible to run a test using non-default settings in several</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text">ways. Firstly, you can include configuration parameters in comments at the top</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text">of the file. For example: to use 3 spaces per tab, start your test with</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text">`// rustfmt-tab_spaces: 3`. Just remember that the comment is part of the input,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text">so include in both the source and target files! It is also possible to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text">explicitly specify the name of the expected output file in the target directory.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text">Use `// rustfmt-target: filename.rs` for this. You can also specify a custom</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text">configuration by using the `rustfmt-config` directive. Rustfmt will then use</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text">that toml file located in `./tests/config/` for its configuration. Including</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text">`// rustfmt-config: small_tabs.toml` will run your test with the configuration</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text">file found at `./tests/config/small_tabs.toml`. The final option is used when the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text">test source file contains no configuration parameter comments. In this case, the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text">test harness looks for a configuration file with the same filename as the test</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text">file in the `./tests/config/` directory, so a test source file named `test-indent.rs`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text">would need a configuration file named `test-indent.toml` in that directory. As an</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text">example, the `issue-1111.rs` test file is configured by the file</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text">`./tests/config/issue-1111.toml`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text">## Debugging</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text">Some `rewrite_*` methods use the `debug!` macro for printing useful information.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text">These messages can be printed by using the environment variable `RUSTFMT_LOG=rustfmt=DEBUG`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text">These traces can be helpful in understanding which part of the code was used</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text">and get a better grasp on the execution flow.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text">## Hack!</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text">Here are some [good starting issues](https://github.com/rust-lang/rustfmt/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text">If you've found areas which need polish and don't have issues, please submit a</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text">PR, don't feel there needs to be an issue.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text">### Guidelines</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text">Rustfmt bootstraps, that is part of its test suite is running itself on its</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text">source code. So, basically, the only style guideline is that you must pass the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text">tests. That ensures that the Rustfmt source code adheres to our own conventions.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text">Talking of tests, if you add a new feature or fix a bug, please also add a test.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L81" href="#L81">81</a><span class="code-text">It's really easy, see above for details. Please run `cargo test` before</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text">submitting a PR to ensure your patch passes all tests, it's pretty quick.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text">Rustfmt is post-1.0 and within major version releases we strive for backwards</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text">compatibility (at least when using the default options). That means any code</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text">which changes Rustfmt's output must be guarded by either an option or a version</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text">check. The latter is implemented as an option called `option`. See the section on</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text">[configuration](#Configuration) below.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text">Please try to avoid leaving `TODO`s in the code. There are a few around, but I</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text">wish there weren't. You can leave `FIXME`s, preferably with an issue number.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L94" href="#L94">94</a><span class="code-text">### Run Rustfmt from source code</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L95" href="#L95">95</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L96" href="#L96">96</a><span class="code-text">You may want to run a version of rustfmt from source code as part of a test or</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L97" href="#L97">97</a><span class="code-text">hacking on the rustfmt codebase. It's strongly discouraged to install a version</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L98" href="#L98">98</a><span class="code-text">of rustfmt from source. Instead, run it using `cargo run`, and `--manifest-path`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L99" href="#L99">99</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L100" href="#L100">100</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L101" href="#L101">101</a><span class="code-text">cargo run --bin cargo-fmt -- --manifest-path path/to/project/you/want2test/Cargo.toml</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L102" href="#L102">102</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L103" href="#L103">103</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L104" href="#L104">104</a><span class="code-text">### Version-gate formatting changes</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L105" href="#L105">105</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L106" href="#L106">106</a><span class="code-text">A change that introduces a different code-formatting should be gated on the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L107" href="#L107">107</a><span class="code-text">`version` configuration. This is to ensure the formatting of the current major</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L108" href="#L108">108</a><span class="code-text">release is preserved, while allowing fixes to be implemented for the next</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L109" href="#L109">109</a><span class="code-text">release.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L110" href="#L110">110</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L111" href="#L111">111</a><span class="code-text">This is done by conditionally guarding the change like so:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L112" href="#L112">112</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L113" href="#L113">113</a><span class="code-text">```rust</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L114" href="#L114">114</a><span class="code-text">if config.version() == Version::One { // if the current major release is 1.x</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L115" href="#L115">115</a><span class="code-text">    // current formatting</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L116" href="#L116">116</a><span class="code-text">} else {</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L117" href="#L117">117</a><span class="code-text">    // new formatting</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L118" href="#L118">118</a><span class="code-text">}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L119" href="#L119">119</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L120" href="#L120">120</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L121" href="#L121">121</a><span class="code-text">This allows the user to apply the next formatting explicitly via the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L122" href="#L122">122</a><span class="code-text">configuration, while being stable by default.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L123" href="#L123">123</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L124" href="#L124">124</a><span class="code-text">When the next major release is done, the code block of the previous formatting</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L125" href="#L125">125</a><span class="code-text">can be deleted, e.g., the first block in the example above when going from `1.x`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L126" href="#L126">126</a><span class="code-text">to `2.x`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L127" href="#L127">127</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L128" href="#L128">128</a><span class="code-text">| Note: Only formatting changes with default options need to be gated. |</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L129" href="#L129">129</a><span class="code-text">| --- |</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L130" href="#L130">130</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L131" href="#L131">131</a><span class="code-text">### A quick tour of Rustfmt</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L132" href="#L132">132</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L133" href="#L133">133</a><span class="code-text">Rustfmt is basically a pretty printer - that is, its mode of operation is to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L134" href="#L134">134</a><span class="code-text">take an AST (abstract syntax tree) and print it in a nice way (including staying</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L135" href="#L135">135</a><span class="code-text">under the maximum permitted width for a line). In order to get that AST, we</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L136" href="#L136">136</a><span class="code-text">first have to parse the source text, we use the Rust compiler's parser to do</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L137" href="#L137">137</a><span class="code-text">that (see [src/lib.rs](src/lib.rs)). We shy away from doing anything too fancy, such as</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L138" href="#L138">138</a><span class="code-text">algebraic approaches to pretty printing, instead relying on an heuristic</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L139" href="#L139">139</a><span class="code-text">approach, 'manually' crafting a string for each AST node. This results in quite</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L140" href="#L140">140</a><span class="code-text">a lot of code, but it is relatively simple.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L141" href="#L141">141</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L142" href="#L142">142</a><span class="code-text">The AST is a tree view of source code. It carries all the semantic information</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L143" href="#L143">143</a><span class="code-text">about the code, but not all of the syntax. In particular, we lose white space</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L144" href="#L144">144</a><span class="code-text">and comments (although doc comments are preserved). Rustfmt uses a view of the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L145" href="#L145">145</a><span class="code-text">AST before macros are expanded, so there are still macro uses in the code. The</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L146" href="#L146">146</a><span class="code-text">arguments to macros are not an AST, but raw tokens - this makes them harder to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L147" href="#L147">147</a><span class="code-text">format.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L148" href="#L148">148</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L149" href="#L149">149</a><span class="code-text">There are different nodes for every kind of item and expression in Rust. For</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L150" href="#L150">150</a><span class="code-text">more details see the source code in the compiler -</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L151" href="#L151">151</a><span class="code-text">[ast.rs](https://github.com/rust-lang/rust/blob/master/compiler/rustc_ast/src/ast.rs) - and/or the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L152" href="#L152">152</a><span class="code-text">[docs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/ast/index.html).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L153" href="#L153">153</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L154" href="#L154">154</a><span class="code-text">Many nodes in the AST (but not all, annoyingly) have a `Span`. A `Span` is a</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L155" href="#L155">155</a><span class="code-text">range in the source code, it can easily be converted to a snippet of source</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L156" href="#L156">156</a><span class="code-text">text. When the AST does not contain enough information for us, we rely heavily</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L157" href="#L157">157</a><span class="code-text">on `Span`s. For example, we can look between spans to try and find comments, or</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L158" href="#L158">158</a><span class="code-text">parse a snippet to see how the user wrote their source code.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L159" href="#L159">159</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L160" href="#L160">160</a><span class="code-text">The downside of using the AST is that we miss some information - primarily white</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L161" href="#L161">161</a><span class="code-text">space and comments. White space is sometimes significant, although mostly we</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L162" href="#L162">162</a><span class="code-text">want to ignore it and make our own. We strive to reproduce all comments, but</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L163" href="#L163">163</a><span class="code-text">this is sometimes difficult. The crufty corners of Rustfmt are where we hack</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L164" href="#L164">164</a><span class="code-text">around the absence of comments in the AST and try to recreate them as best we</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L165" href="#L165">165</a><span class="code-text">can.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L166" href="#L166">166</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L167" href="#L167">167</a><span class="code-text">Our primary tool here is to look between spans for text we've missed. For</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L168" href="#L168">168</a><span class="code-text">example, in a function call `foo(a, b)`, we have spans for `a` and `b`, in this</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L169" href="#L169">169</a><span class="code-text">case, there is only a comma and a single space between the end of `a` and the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L170" href="#L170">170</a><span class="code-text">start of `b`, so there is nothing much to do. But if we look at</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L171" href="#L171">171</a><span class="code-text">`foo(a /* a comment */, b)`, then between `a` and `b` we find the comment.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L172" href="#L172">172</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L173" href="#L173">173</a><span class="code-text">At a higher level, Rustfmt has machinery so that we account for text between</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L174" href="#L174">174</a><span class="code-text">'top level' items. Then we can reproduce that text pretty much verbatim. We only</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L175" href="#L175">175</a><span class="code-text">count spans we actually reformat, so if we can't format a span it is not missed</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L176" href="#L176">176</a><span class="code-text">completely but is reproduced in the output without being formatted. This is</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L177" href="#L177">177</a><span class="code-text">mostly handled in [src/missed_spans.rs](src/missed_spans.rs). See also `FmtVisitor::last_pos` in</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L178" href="#L178">178</a><span class="code-text">[src/visitor.rs](src/visitor.rs).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L179" href="#L179">179</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L180" href="#L180">180</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L181" href="#L181">181</a><span class="code-text">#### Some important elements</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L182" href="#L182">182</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L183" href="#L183">183</a><span class="code-text">At the highest level, Rustfmt uses a `Visitor` implementation called `FmtVisitor`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L184" href="#L184">184</a><span class="code-text">to walk the AST. This is in [src/visitor.rs](src/visitor.rs). This is really just used to walk</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L185" href="#L185">185</a><span class="code-text">items, rather than the bodies of functions. We also cover macros and attributes</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L186" href="#L186">186</a><span class="code-text">here. Most methods of the visitor call out to `Rewrite` implementations that</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L187" href="#L187">187</a><span class="code-text">then walk their own children.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L188" href="#L188">188</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L189" href="#L189">189</a><span class="code-text">The `Rewrite` trait is defined in [src/rewrite.rs](src/rewrite.rs). It is implemented for many</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L190" href="#L190">190</a><span class="code-text">things that can be rewritten, mostly AST nodes. It has a single function,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L191" href="#L191">191</a><span class="code-text">`rewrite`, which is called to rewrite `self` into an `Option&lt;String&gt;`. The</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L192" href="#L192">192</a><span class="code-text">arguments are `width` which is the horizontal space we write into and `offset`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L193" href="#L193">193</a><span class="code-text">which is how much we are currently indented from the lhs of the page. We also</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L194" href="#L194">194</a><span class="code-text">take a context which contains information used for parsing, the current block</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L195" href="#L195">195</a><span class="code-text">indent, and a configuration (see below).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L196" href="#L196">196</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L197" href="#L197">197</a><span class="code-text">##### Rewrite and Indent</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L198" href="#L198">198</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L199" href="#L199">199</a><span class="code-text">To understand the indents, consider</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L200" href="#L200">200</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L201" href="#L201">201</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L202" href="#L202">202</a><span class="code-text">impl Foo {</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L203" href="#L203">203</a><span class="code-text">    fn foo(...) {</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L204" href="#L204">204</a><span class="code-text">        bar(argument_one,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L205" href="#L205">205</a><span class="code-text">            baz());</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L206" href="#L206">206</a><span class="code-text">    }</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L207" href="#L207">207</a><span class="code-text">}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L208" href="#L208">208</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L209" href="#L209">209</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L210" href="#L210">210</a><span class="code-text">When formatting the `bar` call we will format the arguments in order, after the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L211" href="#L211">211</a><span class="code-text">first one we know we are working on multiple lines (imagine it is longer than</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L212" href="#L212">212</a><span class="code-text">written). So, when we come to the second argument, the indent we pass to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L213" href="#L213">213</a><span class="code-text">`rewrite` is 12, which puts us under the first argument. The current block</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L214" href="#L214">214</a><span class="code-text">indent (stored in the context) is 8. The former is used for visual indenting</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L215" href="#L215">215</a><span class="code-text">(when objects are vertically aligned with some marker), the latter is used for</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L216" href="#L216">216</a><span class="code-text">block indenting (when objects are tabbed in from the lhs). The width available</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L217" href="#L217">217</a><span class="code-text">for `baz()` will be the maximum width, minus the space used for indenting, minus</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L218" href="#L218">218</a><span class="code-text">the space used for the `);`. (Note that actual argument formatting does not</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L219" href="#L219">219</a><span class="code-text">quite work like this, but it's close enough).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L220" href="#L220">220</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L221" href="#L221">221</a><span class="code-text">The `rewrite` function returns an `Option` - either we successfully rewrite and</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L222" href="#L222">222</a><span class="code-text">return the rewritten string for the caller to use, or we fail to rewrite and</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L223" href="#L223">223</a><span class="code-text">return `None`. This could be because Rustfmt encounters something it doesn't</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L224" href="#L224">224</a><span class="code-text">know how to reformat, but more often it is because Rustfmt can't fit the item</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L225" href="#L225">225</a><span class="code-text">into the required width. How to handle this is up to the caller. Often the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L226" href="#L226">226</a><span class="code-text">caller just gives up, ultimately relying on the missed spans system to paste in</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L227" href="#L227">227</a><span class="code-text">the un-formatted source. A better solution (although not performed in many</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L228" href="#L228">228</a><span class="code-text">places) is for the caller to shuffle around some of its other items to make</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L229" href="#L229">229</a><span class="code-text">more width, then call the function again with more space.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L230" href="#L230">230</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L231" href="#L231">231</a><span class="code-text">Since it is common for callers to bail out when a callee fails, we often use a</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L232" href="#L232">232</a><span class="code-text">`?` operator to make this pattern more succinct.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L233" href="#L233">233</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L234" href="#L234">234</a><span class="code-text">One way we might find out that we don't have enough space is when computing how much</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L235" href="#L235">235</a><span class="code-text">space we have. Something like `available_space = budget - overhead`. Since</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L236" href="#L236">236</a><span class="code-text">widths are unsized integers, this would cause underflow. Therefore we use</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L237" href="#L237">237</a><span class="code-text">checked subtraction: `available_space = budget.checked_sub(overhead)?`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L238" href="#L238">238</a><span class="code-text">`checked_sub` returns an `Option`, and if we would underflow `?` returns</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L239" href="#L239">239</a><span class="code-text">`None`, otherwise, we proceed with the computed space.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L240" href="#L240">240</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L241" href="#L241">241</a><span class="code-text">##### Rewrite of list-like expressions</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L242" href="#L242">242</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L243" href="#L243">243</a><span class="code-text">Much of the syntax in Rust is lists: lists of arguments, lists of fields, lists of</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L244" href="#L244">244</a><span class="code-text">array elements, etc. We have some generic code to handle lists, including how to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L245" href="#L245">245</a><span class="code-text">space them in horizontal and vertical space, indentation, comments between</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L246" href="#L246">246</a><span class="code-text">items, trailing separators, etc. However, since there are so many options, the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L247" href="#L247">247</a><span class="code-text">code is a bit complex. Look in [src/lists.rs](src/lists.rs). `write_list` is the key function,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L248" href="#L248">248</a><span class="code-text">and `ListFormatting` the key structure for configuration. You'll need to make a</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L249" href="#L249">249</a><span class="code-text">`ListItems` for input, this is usually done using `itemize_list`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L250" href="#L250">250</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L251" href="#L251">251</a><span class="code-text">##### Configuration</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L252" href="#L252">252</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L253" href="#L253">253</a><span class="code-text">Rustfmt strives to be highly configurable. Often the first part of a patch is</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L254" href="#L254">254</a><span class="code-text">creating a configuration option for the feature you are implementing. All</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L255" href="#L255">255</a><span class="code-text">handling of configuration options is done in [src/config/mod.rs](src/config/mod.rs). Look for the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L256" href="#L256">256</a><span class="code-text">`create_config!` macro at the end of the file for all the options. The rest of</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L257" href="#L257">257</a><span class="code-text">the file defines a bunch of enums used for options, and the machinery to produce</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L258" href="#L258">258</a><span class="code-text">the config struct and parse a config file, etc. Checking an option is done by</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L259" href="#L259">259</a><span class="code-text">accessing the correct field on the config struct, e.g., `config.max_width()`. Most</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L260" href="#L260">260</a><span class="code-text">functions have a `Config`, or one can be accessed via a visitor or context of</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L261" href="#L261">261</a><span class="code-text">some kind.</span></span></pre></div></div>
</main>
</body>
</html>
