X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=Configurations.md;h=6c4e7dc77604d8802dfdde3263278d0dc70bafb8;hb=a92a1cb51283bc6861bb1bb33b2b34c36b5d16bd;hp=5334ca6e4c28065b890373ae33d3fe758e7c670d;hpb=4633786848f79a8a8bc3b8679b7b40418f1f0f7f;p=rust.git

diff --git a/Configurations.md b/Configurations.md
index 5334ca6e4c2..6c4e7dc7760 100644
--- a/Configurations.md
+++ b/Configurations.md
@@ -6,12 +6,12 @@ A possible content of `rustfmt.toml` or `.rustfmt.toml` might look like this:
 
 ```toml
 indent_style = "Block"
-reorder_imported_names = true
+reorder_imports = false
 ```
 
 Each configuration option is either stable or unstable.
 Stable options can be used directly, while unstable options are opt-in.
-To enable unstable options, set `unstable_features = true` in `rustfmt.toml` or pass `--unstable-options` to rustfmt.
+To enable unstable options, set `unstable_features = true` in `rustfmt.toml` or pass `--unstable-features` to rustfmt.
 
 # Configuration Options
 
@@ -63,21 +63,34 @@ fn main() {
 #### `"Block"` (default):
 
 ```rust
-if lorem_ipsum &&
-    dolor_sit &&
-    amet_consectetur
-{
-    // ...
+fn main() {
+    if lorem_ipsum
+        && dolor_sit
+        && amet_consectetur
+        && lorem_sit
+        && dolor_consectetur
+        && amet_ipsum
+        && lorem_consectetur
+    {
+        // ...
+    }
 }
 ```
 
 #### `"Visual"`:
 
 ```rust
-if lorem_ipsum &&
-   dolor_sit &&
-   amet_consectetur {
-    // ...
+fn main() {
+    if lorem_ipsum
+       && dolor_sit
+       && amet_consectetur
+       && lorem_sit
+       && dolor_consectetur
+       && amet_ipsum
+       && lorem_consectetur
+    {
+        // ...
+    }
 }
 ```
 
@@ -339,7 +352,8 @@ fn main() {
     let or = foofoofoofoofoofoofoofoofoofoofoofoofoofoofoofoo
         || barbarbarbarbarbarbarbarbarbarbarbarbarbarbarbar;
 
-    let sum = 123456789012345678901234567890 + 123456789012345678901234567890
+    let sum = 123456789012345678901234567890
+        + 123456789012345678901234567890
         + 123456789012345678901234567890;
 
     let range = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
@@ -354,7 +368,8 @@ fn main() {
     let or = foofoofoofoofoofoofoofoofoofoofoofoofoofoofoofoo ||
         barbarbarbarbarbarbarbarbarbarbarbarbarbarbarbar;
 
-    let sum = 123456789012345678901234567890 + 123456789012345678901234567890 +
+    let sum = 123456789012345678901234567890 +
+        123456789012345678901234567890 +
         123456789012345678901234567890;
 
     let range = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa..
@@ -576,24 +591,26 @@ Don't reformat anything
 
 ## `error_on_line_overflow`
 
-Error if unable to get all lines within `max_width`
+Error if Rustfmt is unable to get all lines within `max_width`, except for comments and string
+literals. If this happens, then it is a bug in Rustfmt. You might be able to work around the bug by
+refactoring your code to avoid long/complex expressions, usually by extracting a local variable or
+using a shorter name.
 
-- **Default value**: `true`
+- **Default value**: `false`
 - **Possible values**: `true`, `false`
 - **Stable**: No
 
 See also [`max_width`](#max_width).
 
-## `error_on_line_overflow_comments`
+## `error_on_unformatted`
 
-Error if unable to get all comment lines within `comment_width`.
+Error if unable to get comments or string literals within `max_width`, or they are left with
+trailing whitespaces.
 
-- **Default value**: `true`
+- **Default value**: `false`
 - **Possible values**: `true`, `false`
 - **Stable**: No
 
-See also [`comment_width`](#comment_width).
-
 ## `fn_args_density`
 
 Argument density in functions
@@ -887,7 +904,7 @@ See also [`control_brace_style`](#control_brace_style).
 
 ## `where_single_line`
 
-To force single line where layout
+Forces the `where` clause to be laid out on a single line.
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
@@ -1037,8 +1054,10 @@ Item layout inside a imports block
 ```rust
 use foo::{xxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyy, zzzzzzzzzzzzzzzzzz};
 
-use foo::{aaaaaaaaaaaaaaaaaa, bbbbbbbbbbbbbbbbbb, cccccccccccccccccc, dddddddddddddddddd,
-          eeeeeeeeeeeeeeeeee, ffffffffffffffffff};
+use foo::{
+    aaaaaaaaaaaaaaaaaa, bbbbbbbbbbbbbbbbbb, cccccccccccccccccc, dddddddddddddddddd,
+    eeeeeeeeeeeeeeeeee, ffffffffffffffffff,
+};
 ```
 
 #### `"Horizontal"`:
@@ -1056,27 +1075,55 @@ use foo::{aaa, bbb, ccc, ddd, eee, fff};
 ```rust
 use foo::{xxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyy, zzzzzzzzzzzzzzzzzz};
 
-use foo::{aaaaaaaaaaaaaaaaaa,
-          bbbbbbbbbbbbbbbbbb,
-          cccccccccccccccccc,
-          dddddddddddddddddd,
-          eeeeeeeeeeeeeeeeee,
-          ffffffffffffffffff};
+use foo::{
+    aaaaaaaaaaaaaaaaaa,
+    bbbbbbbbbbbbbbbbbb,
+    cccccccccccccccccc,
+    dddddddddddddddddd,
+    eeeeeeeeeeeeeeeeee,
+    ffffffffffffffffff,
+};
 ```
 
 #### `"Vertical"`:
 
 ```rust
-use foo::{xxx,
-          yyy,
-          zzz};
+use foo::{
+    xxx,
+    yyy,
+    zzz,
+};
+
+use foo::{
+    aaa,
+    bbb,
+    ccc,
+    ddd,
+    eee,
+    fff,
+};
+```
+
+## `merge_imports`
+
+Merge multiple imports into a single nested import.
+
+- **Default value**: `false`
+- **Possible values**: `true`, `false`
+- **Stable**: No
+
+#### `false` (default):
+
+```rust
+use foo::{a, c, d};
+use foo::{b, g};
+use foo::{e, f};
+```
+
+#### `true`:
 
-use foo::{aaa,
-          bbb,
-          ccc,
-          ddd,
-          eee,
-          fff};
+```rust
+use foo::{a, b, c, d, e, f, g};
 ```
 
 
@@ -1161,37 +1208,40 @@ Force multiline closure and match arm bodies to be wrapped in a block
 #### `false` (default):
 
 ```rust
-result.and_then(|maybe_value| match maybe_value {
-    None => ...,
-    Some(value) => ...,
-})
+fn main() {
+    result.and_then(|maybe_value| match maybe_value {
+        None => foo(),
+        Some(value) => bar(),
+    });
 
-match lorem {
-    None => if ipsum {
-        println!("Hello World");
-    },
-    Some(dolor) => ...,
+    match lorem {
+        None => if ipsum {
+            println!("Hello World");
+        },
+        Some(dolor) => foo(),
+    }
 }
 ```
 
 #### `true`:
 
 ```rust
+fn main() {
+    result.and_then(|maybe_value| {
+        match maybe_value {
+            None => foo(),
+            Some(value) => bar(),
+        }
+    });
 
-result.and_then(|maybe_value| {
-    match maybe_value {
-        None => ...,
-        Some(value) => ...,
-    }
-})
-
-match lorem {
-    None => {
-        if ipsum {
-            println!("Hello World");
+    match lorem {
+        None => {
+            if ipsum {
+                println!("Hello World");
+            }
         }
+        Some(dolor) => foo(),
     }
-    Some(dolor) => ...,
 }
 ```
 
@@ -1210,7 +1260,7 @@ Convert /* */ comments to // comments where possible
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
-- **Stable**: Yes
+- **Stable**: No
 
 #### `false` (default):
 
@@ -1232,46 +1282,40 @@ fn dolor() -> usize {}
 fn adipiscing() -> usize {}
 ```
 
-## `reorder_imported_names`
+## `remove_nested_parens`
 
-Reorder lists of names in import statements alphabetically
+Remove nested parens.
 
-- **Default value**: `false`
+- **Default value**: `true`,
 - **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: Yes
 
-#### `false` (default):
 
+#### `true` (default):
 ```rust
-use super::{lorem, ipsum, dolor, sit};
+fn main() {
+    (foo());
+}
 ```
 
-#### `true`:
-
+#### `false`:
 ```rust
-use super::{dolor, ipsum, lorem, sit};
+fn main() {
+    ((((foo()))));
+}
 ```
 
-See also [`reorder_imports`](#reorder_imports).
 
 ## `reorder_imports`
 
-Reorder import statements alphabetically
+Reorder import and extern crate statements alphabetically in groups (a group is
+separated by a newline).
 
-- **Default value**: `false`
+- **Default value**: `true`
 - **Possible values**: `true`, `false`
-- **Stable**: No
-
-#### `false` (default):
-
-```rust
-use lorem;
-use ipsum;
-use dolor;
-use sit;
-```
+- **Stable**: Yes
 
-#### `true`:
+#### `true` (default):
 
 ```rust
 use dolor;
@@ -1280,107 +1324,86 @@ use lorem;
 use sit;
 ```
 
-See also [`reorder_imported_names`](#reorder_imported_names), [`reorder_imports_in_group`](#reorder_imports_in_group).
-
-## `reorder_imports_in_group`
-
-Reorder import statements in group
-
-- **Default value**: `false`
-- **Possible values**: `true`, `false`
-- **Stable**: No
-
-**Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
-
-#### `false` (default):
+#### `false`:
 
 ```rust
-use std::mem;
-use std::io;
-
 use lorem;
 use ipsum;
 use dolor;
 use sit;
 ```
 
-#### `true`:
-
-```rust
-use std::io;
-use std::mem;
-
-use dolor;
-use ipsum;
-use lorem;
-use sit;
-```
-
-See also [`reorder_imports`](#reorder_imports).
 
-## `reorder_extern_crates`
+## `reorder_modules`
 
-Reorder `extern crate` statements alphabetically
+Reorder `mod` declarations alphabetically in group.
 
 - **Default value**: `true`
 - **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: Yes
 
-#### `true` (default):
+#### `true` (default)
 
 ```rust
-extern crate dolor;
-extern crate ipsum;
-extern crate lorem;
-extern crate sit;
+mod a;
+mod b;
+
+mod dolor;
+mod ipsum;
+mod lorem;
+mod sit;
 ```
 
-#### `false`:
+#### `false`
 
 ```rust
-extern crate lorem;
-extern crate ipsum;
-extern crate dolor;
-extern crate sit;
+mod b;
+mod a;
+
+mod lorem;
+mod ipsum;
+mod dolor;
+mod sit;
 ```
 
-See also [`reorder_extern_crates_in_group`](#reorder_extern_crates_in_group).
+**Note** `mod` with `#[macro_export]` will not be reordered since that could change the semantic
+of the original source code.
 
-## `reorder_extern_crates_in_group`
+## `reorder_impl_items`
 
-Reorder `extern crate` statements in group
+Reorder impl items. `type` and `const` are put first, then macros and methods.
 
-- **Default value**: `true`
+- **Default value**: `false`
 - **Possible values**: `true`, `false`
 - **Stable**: No
 
-**Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
-
-#### `true` (default):
+#### `false` (default)
 
 ```rust
-extern crate a;
-extern crate b;
+struct Dummy;
+
+impl Iterator for Dummy {
+    fn next(&mut self) -> Option<Self::Item> {
+        None
+    }
 
-extern crate dolor;
-extern crate ipsum;
-extern crate lorem;
-extern crate sit;
+    type Item = i32;
+}
 ```
 
-#### `false`:
+#### `true`
 
 ```rust
-extern crate b;
-extern crate a;
+struct Dummy;
 
-extern crate lorem;
-extern crate ipsum;
-extern crate dolor;
-extern crate sit;
-```
+impl Iterator for Dummy {
+    type Item = i32;
 
-See also [`reorder_extern_crates`](#reorder_extern_crates).
+    fn next(&mut self) -> Option<Self::Item> {
+        None
+    }
+}
+```
 
 ## `report_todo`
 
@@ -1567,48 +1590,6 @@ fn main() {
 }
 ```
 
-## `spaces_within_parens_and_brackets`
-
-Put spaces within non-empty generic arguments, parentheses, and square brackets
-
-- **Default value**: `false`
-- **Possible values**: `true`, `false`
-- **Stable**: No
-
-#### `false` (default):
-
-```rust
-// generic arguments
-fn lorem<T: Eq>(t: T) {
-    // body
-}
-
-// non-empty parentheses
-fn lorem<T: Eq>(t: T) {
-    let lorem = (ipsum, dolor);
-}
-
-// non-empty square brackets
-let lorem: [usize; 2] = [ipsum, dolor];
-```
-
-#### `true`:
-
-```rust
-// generic arguments
-fn lorem< T: Eq >(t: T) {
-    // body
-}
-
-// non-empty parentheses
-fn lorem<T: Eq>( t: T ) {
-    let lorem = ( ipsum, dolor );
-}
-
-// non-empty square brackets
-let lorem: [ usize; 2 ] = [ ipsum, dolor ];
-```
-
 ## `struct_lit_single_line`
 
 Put small struct literals on a single line
@@ -1620,16 +1601,20 @@ Put small struct literals on a single line
 #### `true` (default):
 
 ```rust
-let lorem = Lorem { ipsum: dolor, sit: amet };
+fn main() {
+    let lorem = Lorem { foo: bar, baz: ofo };
+}
 ```
 
 #### `false`:
 
 ```rust
-let lorem = Lorem {
-    ipsum: dolor,
-    sit: amet,
-};
+fn main() {
+    let lorem = Lorem {
+        foo: bar,
+        baz: ofo,
+    };
+}
 ```
 
 See also: [`indent_style`](#indent_style).
@@ -1649,7 +1634,8 @@ Number of spaces per tab
 fn lorem() {
     let ipsum = dolor();
     let sit = vec![
-        "amet consectetur adipiscing elit."
+        "amet consectetur adipiscing elit amet",
+        "consectetur adipiscing elit amet consectetur.",
     ];
 }
 ```
@@ -1660,7 +1646,8 @@ fn lorem() {
 fn lorem() {
   let ipsum = dolor();
   let sit = vec![
-    "amet consectetur adipiscing elit."
+    "amet consectetur adipiscing elit amet",
+    "consectetur adipiscing elit amet consectetur.",
   ];
 }
 ```
@@ -1679,43 +1666,49 @@ How to handle trailing commas for lists
 #### `"Vertical"` (default):
 
 ```rust
-let Lorem { ipsum, dolor, sit } = amet;
-let Lorem {
-    ipsum,
-    dolor,
-    sit,
-    amet,
-    consectetur,
-    adipiscing,
-} = elit;
+fn main() {
+    let Lorem { ipsum, dolor, sit } = amet;
+    let Lorem {
+        ipsum,
+        dolor,
+        sit,
+        amet,
+        consectetur,
+        adipiscing,
+    } = elit;
+}
 ```
 
 #### `"Always"`:
 
 ```rust
-let Lorem { ipsum, dolor, sit, } = amet;
-let Lorem {
-    ipsum,
-    dolor,
-    sit,
-    amet,
-    consectetur,
-    adipiscing,
-} = elit;
+fn main() {
+    let Lorem { ipsum, dolor, sit, } = amet;
+    let Lorem {
+        ipsum,
+        dolor,
+        sit,
+        amet,
+        consectetur,
+        adipiscing,
+    } = elit;
+}
 ```
 
 #### `"Never"`:
 
 ```rust
-let Lorem { ipsum, dolor, sit } = amet;
-let Lorem {
-    ipsum,
-    dolor,
-    sit,
-    amet,
-    consectetur,
-    adipiscing
-} = elit;
+fn main() {
+    let Lorem { ipsum, dolor, sit } = amet;
+    let Lorem {
+        ipsum,
+        dolor,
+        sit,
+        amet,
+        consectetur,
+        adipiscing
+    } = elit;
+}
 ```
 
 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
@@ -1754,7 +1747,7 @@ Determines if `+` or `=` are wrapped in spaces in the punctuation of types
 
 ```rust
 fn lorem<Ipsum: Dolor + Sit = Amet>() {
-	// body
+    // body
 }
 ```
 
@@ -1762,7 +1755,49 @@ fn lorem<Ipsum: Dolor + Sit = Amet>() {
 
 ```rust
 fn lorem<Ipsum: Dolor+Sit=Amet>() {
-	// body
+    // body
+}
+```
+
+## `use_field_init_shorthand`
+
+Use field initialize shorthand if possible.
+
+- **Default value**: `false`
+- **Possible values**: `true`, `false`
+- **Stable**: Yes
+
+#### `false` (default):
+
+```rust
+struct Foo {
+    x: u32,
+    y: u32,
+    z: u32,
+}
+
+fn main() {
+    let x = 1;
+    let y = 2;
+    let z = 3;
+    let a = Foo { x: x, y: y, z: z };
+}
+```
+
+#### `true`:
+
+```rust
+struct Foo {
+    x: u32,
+    y: u32,
+    z: u32,
+}
+
+fn main() {
+    let x = 1;
+    let y = 2;
+    let z = 3;
+    let a = Foo { x, y, z };
 }
 ```
 
@@ -1772,18 +1807,22 @@ Replace uses of the try! macro by the ? shorthand
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: Yes
 
 #### `false` (default):
 
 ```rust
-let lorem = try!(ipsum.map(|dolor|dolor.sit()));
+fn main() {
+    let lorem = try!(ipsum.map(|dolor| dolor.sit()));
+}
 ```
 
 #### `true`:
 
 ```rust
-let lorem = ipsum.map(|dolor| dolor.sit())?;
+fn main() {
+    let lorem = ipsum.map(|dolor| dolor.sit())?;
+}
 ```
 
 
@@ -1793,7 +1832,7 @@ Break comments to fit on the line
 
 - **Default value**: `false`
 - **Possible values**: `true`, `false`
-- **Stable**: Yes
+- **Stable**: No
 
 #### `false` (default):
 
@@ -1822,33 +1861,30 @@ Wrap the body of arms in blocks when it does not fit on the same line with the p
 #### `true` (default):
 
 ```rust
-match lorem {
-    true => {
-        foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x)
+fn main() {
+    match lorem {
+        true => {
+            foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x)
+        }
+        false => println!("{}", sit),
     }
-    false => println!("{}", sit),
 }
 ```
 
 #### `false`:
 
 ```rust
-match lorem {
-    true =>
-        foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x),
-    false => println!("{}", sit),
+fn main() {
+    match lorem {
+        true =>
+            foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x),
+        false => println!("{}", sit),
+    }
 }
 ```
 
 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
 
-## `write_mode`
-
-What Write Mode to use when none is supplied: Replace, Overwrite, Display, Diff, Coverage
-
-- **Default value**: `"Overwrite"`
-- **Possible values**: `"Checkstyle"`, `"Coverage"`, `"Diff"`, `"Display"`, `"Overwrite"`, `"Plain"`, `"Replace"`
-- **Stable**: No
 
 ## `blank_lines_upper_bound`
 
@@ -1863,6 +1899,8 @@ lines are found, they are trimmed down to match this integer.
 Original Code:
 
 ```rust
+#![rustfmt::skip]
+
 fn foo() {
     println!("a");
 }
@@ -1920,6 +1958,8 @@ them, additional blank lines are inserted.
 Original Code (rustfmt will not change it with the default value of `0`):
 
 ```rust
+#![rustfmt::skip]
+
 fn foo() {
     println!("a");
 }
@@ -1943,3 +1983,92 @@ fn bar() {
     println!("c");
 }
 ```
+
+
+## `required_version`
+
+Require a specific version of rustfmt. If you want to make sure that the
+specific version of rustfmt is used in your CI, use this option.
+
+- **Default value**: `CARGO_PKG_VERSION`
+- **Possible values**: any published version (e.g. `"0.3.8"`)
+- **Stable**: No
+
+## `hide_parse_errors`
+
+Do not show parse errors if the parser failed to parse files.
+
+- **Default value**: `false`
+- **Possible values**: `true`, `false`
+- **Stable**: No
+
+## `color`
+
+Whether to use colored output or not.
+
+- **Default value**: `"Auto"`
+- **Possible values**: "Auto", "Always", "Never"
+- **Stable**: No
+
+## `unstable_features`
+
+Enable unstable features on stable channel.
+
+- **Default value**: `false`
+- **Possible values**: `true`, `false`
+- **Stable**: No
+
+## `license_template_path`
+
+Check whether beginnings of files match a license template.
+
+- **Default value**: `""``
+- **Possible values**: path to a license template file
+- **Stable**: No
+
+A license template is a plain text file which is matched literally against the
+beginning of each source file, except for `{}`-delimited blocks, which are
+matched as regular expressions. The following license template therefore
+matches strings like `// Copyright 2017 The Rust Project Developers.`, `//
+Copyright 2018 The Rust Project Developers.`, etc.:
+
+```
+// Copyright {\d+} The Rust Project Developers.
+```
+
+`\{`, `\}` and `\\` match literal braces / backslashes.
+
+## `ignore`
+
+Skip formatting the specified files and directories.
+
+- **Default value**: format every files
+- **Possible values**: See an example below
+- **Stable**: No
+
+### Example
+
+If you want to ignore specific files, put the following to your config file:
+
+```toml
+ignore = [
+    "src/types.rs",
+    "src/foo/bar.rs",
+]
+```
+
+If you want to ignore every file under `examples/`, put the following to your config file:
+
+```toml
+ignore [
+    "examples",
+]
+```
+
+## `emit_mode`
+
+Internal option
+
+## `make_backup`
+
+Internal option, use `--backup`