Configurations.md

   1 # Configuring Rustfmt
   2
   3 Rustfmt is designed to be very configurable. You can create a TOML file called `rustfmt.toml` or `.rustfmt.toml`, place it in the project or any other parent directory and it will apply the options in that file.
   4
   5 A possible content of `rustfmt.toml` or `.rustfmt.toml` might look like this:
   6
   7 ```toml
   8 indent_style = "Block"
   9 reorder_imported_names = true
  10 ```
  11
  12 Each configuration option is either stable or unstable.
  13 Stable options can be used directly, while unstable options are opt-in.
  14 To enable unstable options, set `unstable_features = true` in `rustfmt.toml` or pass `--unstable-options` to rustfmt.
  15
  16 # Configuration Options
  17
  18 Below you find a detailed visual guide on all the supported configuration options of rustfmt:
  19
  20
  21 ## `indent_style`
  22
  23 Indent on expressions or items.
  24
  25 - **Default value**: `"Block"`
  26 - **Possible values**: `"Block"`, `"Visual"`
  27 - **Stable**: No
  28
  29 ### Array
  30
  31 #### `"Block"` (default):
  32
  33 ```rust
  34 fn main() {
  35     let lorem = vec![
  36         "ipsum",
  37         "dolor",
  38         "sit",
  39         "amet",
  40         "consectetur",
  41         "adipiscing",
  42         "elit",
  43     ];
  44 }
  45 ```
  46
  47 #### `"Visual"`:
  48
  49 ```rust
  50 fn main() {
  51     let lorem = vec!["ipsum",
  52                      "dolor",
  53                      "sit",
  54                      "amet",
  55                      "consectetur",
  56                      "adipiscing",
  57                      "elit"];
  58 }
  59 ```
  60
  61 ### Control flow
  62
  63 #### `"Block"` (default):
  64
  65 ```rust
  66 if lorem_ipsum &&
  67     dolor_sit &&
  68     amet_consectetur
  69 {
  70     // ...
  71 }
  72 ```
  73
  74 #### `"Visual"`:
  75
  76 ```rust
  77 if lorem_ipsum &&
  78    dolor_sit &&
  79    amet_consectetur {
  80     // ...
  81 }
  82 ```
  83
  84 See also: [`control_brace_style`](#control_brace_style).
  85
  86 ### Function arguments
  87
  88 #### `"Block"` (default):
  89
  90 ```rust
  91 fn lorem() {}
  92
  93 fn lorem(ipsum: usize) {}
  94
  95 fn lorem(
  96     ipsum: usize,
  97     dolor: usize,
  98     sit: usize,
  99     amet: usize,
 100     consectetur: usize,
 101     adipiscing: usize,
 102     elit: usize,
 103 ) {
 104     // body
 105 }
 106 ```
 107
 108 #### `"Visual"`:
 109
 110 ```rust
 111 fn lorem() {}
 112
 113 fn lorem(ipsum: usize) {}
 114
 115 fn lorem(ipsum: usize,
 116          dolor: usize,
 117          sit: usize,
 118          amet: usize,
 119          consectetur: usize,
 120          adipiscing: usize,
 121          elit: usize) {
 122     // body
 123 }
 124 ```
 125
 126 ### Function calls
 127
 128 #### `"Block"` (default):
 129
 130 ```rust
 131 fn main() {
 132     lorem(
 133         "lorem",
 134         "ipsum",
 135         "dolor",
 136         "sit",
 137         "amet",
 138         "consectetur",
 139         "adipiscing",
 140         "elit",
 141     );
 142 }
 143 ```
 144
 145 #### `"Visual"`:
 146
 147 ```rust
 148 fn main() {
 149     lorem("lorem",
 150           "ipsum",
 151           "dolor",
 152           "sit",
 153           "amet",
 154           "consectetur",
 155           "adipiscing",
 156           "elit");
 157 }
 158 ```
 159
 160 ### Generics
 161
 162 #### `"Block"` (default):
 163
 164 ```rust
 165 fn lorem<
 166     Ipsum: Eq = usize,
 167     Dolor: Eq = usize,
 168     Sit: Eq = usize,
 169     Amet: Eq = usize,
 170     Adipiscing: Eq = usize,
 171     Consectetur: Eq = usize,
 172     Elit: Eq = usize,
 173 >(
 174     ipsum: Ipsum,
 175     dolor: Dolor,
 176     sit: Sit,
 177     amet: Amet,
 178     adipiscing: Adipiscing,
 179     consectetur: Consectetur,
 180     elit: Elit,
 181 ) -> T {
 182     // body
 183 }
 184 ```
 185
 186 #### `"Visual"`:
 187
 188 ```rust
 189 fn lorem<Ipsum: Eq = usize,
 190          Dolor: Eq = usize,
 191          Sit: Eq = usize,
 192          Amet: Eq = usize,
 193          Adipiscing: Eq = usize,
 194          Consectetur: Eq = usize,
 195          Elit: Eq = usize>(
 196     ipsum: Ipsum,
 197     dolor: Dolor,
 198     sit: Sit,
 199     amet: Amet,
 200     adipiscing: Adipiscing,
 201     consectetur: Consectetur,
 202     elit: Elit)
 203     -> T {
 204     // body
 205 }
 206 ```
 207
 208 #### Struct
 209
 210 #### `"Block"` (default):
 211
 212 ```rust
 213 fn main() {
 214     let lorem = Lorem {
 215         ipsum: dolor,
 216         sit: amet,
 217     };
 218 }
 219 ```
 220
 221 #### `"Visual"`:
 222
 223 ```rust
 224 fn main() {
 225     let lorem = Lorem { ipsum: dolor,
 226                         sit: amet, };
 227 }
 228 ```
 229
 230 See also: [`struct_lit_single_line`](#struct_lit_single_line), [`indent_style`](#indent_style).
 231
 232 ### Where predicates
 233
 234 #### `"Block"` (default):
 235
 236 ```rust
 237 fn lorem<Ipsum, Dolor, Sit, Amet>() -> T
 238 where
 239     Ipsum: Eq,
 240     Dolor: Eq,
 241     Sit: Eq,
 242     Amet: Eq,
 243 {
 244     // body
 245 }
 246 ```
 247
 248 #### `"Visual"`:
 249
 250 ```rust
 251 fn lorem<Ipsum, Dolor, Sit, Amet>() -> T
 252     where Ipsum: Eq,
 253           Dolor: Eq,
 254           Sit: Eq,
 255           Amet: Eq
 256 {
 257     // body
 258 }
 259 ```
 260
 261 ## `use_small_heuristics`
 262
 263 Whether to use different formatting for items and expressions if they satisfy a heuristic notion of 'small'.
 264
 265 - **Default value**: `true`
 266 - **Possible values**: `true`, `false`
 267 - **Stable**: No
 268
 269 #### `true` (default):
 270
 271 ```rust
 272 enum Lorem {
 273     Ipsum,
 274     Dolor(bool),
 275     Sit { amet: Consectetur, adipiscing: Elit },
 276 }
 277
 278 fn main() {
 279     lorem(
 280         "lorem",
 281         "ipsum",
 282         "dolor",
 283         "sit",
 284         "amet",
 285         "consectetur",
 286         "adipiscing",
 287     );
 288
 289     let lorem = Lorem {
 290         ipsum: dolor,
 291         sit: amet,
 292     };
 293     let lorem = Lorem { ipsum: dolor };
 294
 295     let lorem = if ipsum { dolor } else { sit };
 296 }
 297 ```
 298
 299 #### `false`:
 300
 301 ```rust
 302 enum Lorem {
 303     Ipsum,
 304     Dolor(bool),
 305     Sit {
 306         amet: Consectetur,
 307         adipiscing: Elit,
 308     },
 309 }
 310
 311 fn main() {
 312     lorem("lorem", "ipsum", "dolor", "sit", "amet", "consectetur", "adipiscing");
 313
 314     let lorem = Lorem {
 315         ipsum: dolor,
 316         sit: amet,
 317     };
 318
 319     let lorem = if ipsum {
 320         dolor
 321     } else {
 322         sit
 323     };
 324 }
 325 ```
 326
 327 ## `binop_separator`
 328
 329 Where to put a binary operator when a binary expression goes multiline.
 330
 331 - **Default value**: `"Front"`
 332 - **Possible values**: `"Front"`, `"Back"`
 333 - **Stable**: No
 334
 335 #### `"Front"` (default):
 336
 337 ```rust
 338 fn main() {
 339     let or = foofoofoofoofoofoofoofoofoofoofoofoofoofoofoofoo
 340         || barbarbarbarbarbarbarbarbarbarbarbarbarbarbarbar;
 341
 342     let sum = 123456789012345678901234567890 + 123456789012345678901234567890
 343         + 123456789012345678901234567890;
 344
 345     let range = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
 346         ..bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb;
 347 }
 348 ```
 349
 350 #### `"Back"`:
 351
 352 ```rust
 353 fn main() {
 354     let or = foofoofoofoofoofoofoofoofoofoofoofoofoofoofoofoo ||
 355         barbarbarbarbarbarbarbarbarbarbarbarbarbarbarbar;
 356
 357     let sum = 123456789012345678901234567890 + 123456789012345678901234567890 +
 358         123456789012345678901234567890;
 359
 360     let range = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa..
 361         bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb;
 362 }
 363 ```
 364
 365 ## `combine_control_expr`
 366
 367 Combine control expressions with function calls.
 368
 369 - **Default value**: `true`
 370 - **Possible values**: `true`, `false`
 371 - **Stable**: No
 372
 373 #### `true` (default):
 374
 375 ```rust
 376 fn example() {
 377     // If
 378     foo!(if x {
 379         foo();
 380     } else {
 381         bar();
 382     });
 383
 384     // IfLet
 385     foo!(if let Some(..) = x {
 386         foo();
 387     } else {
 388         bar();
 389     });
 390
 391     // While
 392     foo!(while x {
 393         foo();
 394         bar();
 395     });
 396
 397     // WhileLet
 398     foo!(while let Some(..) = x {
 399         foo();
 400         bar();
 401     });
 402
 403     // ForLoop
 404     foo!(for x in y {
 405         foo();
 406         bar();
 407     });
 408
 409     // Loop
 410     foo!(loop {
 411         foo();
 412         bar();
 413     });
 414 }
 415 ```
 416
 417 #### `false`:
 418
 419 ```rust
 420 fn example() {
 421     // If
 422     foo!(
 423         if x {
 424             foo();
 425         } else {
 426             bar();
 427         }
 428     );
 429
 430     // IfLet
 431     foo!(
 432         if let Some(..) = x {
 433             foo();
 434         } else {
 435             bar();
 436         }
 437     );
 438
 439     // While
 440     foo!(
 441         while x {
 442             foo();
 443             bar();
 444         }
 445     );
 446
 447     // WhileLet
 448     foo!(
 449         while let Some(..) = x {
 450             foo();
 451             bar();
 452         }
 453     );
 454
 455     // ForLoop
 456     foo!(
 457         for x in y {
 458             foo();
 459             bar();
 460         }
 461     );
 462
 463     // Loop
 464     foo!(
 465         loop {
 466             foo();
 467             bar();
 468         }
 469     );
 470 }
 471 ```
 472
 473 ## `comment_width`
 474
 475 Maximum length of comments. No effect unless`wrap_comments = true`.
 476
 477 - **Default value**: `80`
 478 - **Possible values**: any positive integer
 479 - **Stable**: No
 480
 481 **Note:** A value of `0` results in [`wrap_comments`](#wrap_comments) being applied regardless of a line's width.
 482
 483 #### `80` (default; comments shorter than `comment_width`):
 484 ```rust
 485 // Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 486 ```
 487
 488 #### `60` (comments longer than `comment_width`):
 489 ```rust
 490 // Lorem ipsum dolor sit amet,
 491 // consectetur adipiscing elit.
 492 ```
 493
 494 See also [`wrap_comments`](#wrap_comments).
 495
 496 ## `condense_wildcard_suffixes`
 497
 498 Replace strings of _ wildcards by a single .. in tuple patterns
 499
 500 - **Default value**: `false`
 501 - **Possible values**: `true`, `false`
 502 - **Stable**: No
 503
 504 #### `false` (default):
 505
 506 ```rust
 507 fn main() {
 508     let (lorem, ipsum, _, _) = (1, 2, 3, 4);
 509     let (lorem, ipsum, ..) = (1, 2, 3, 4);
 510 }
 511 ```
 512
 513 #### `true`:
 514
 515 ```rust
 516 fn main() {
 517     let (lorem, ipsum, ..) = (1, 2, 3, 4);
 518 }
 519 ```
 520
 521 ## `control_brace_style`
 522
 523 Brace style for control flow constructs
 524
 525 - **Default value**: `"AlwaysSameLine"`
 526 - **Possible values**: `"AlwaysNextLine"`, `"AlwaysSameLine"`, `"ClosingNextLine"`
 527 - **Stable**: No
 528
 529 #### `"AlwaysSameLine"` (default):
 530
 531 ```rust
 532 fn main() {
 533     if lorem {
 534         println!("ipsum!");
 535     } else {
 536         println!("dolor!");
 537     }
 538 }
 539 ```
 540
 541 #### `"AlwaysNextLine"`:
 542
 543 ```rust
 544 fn main() {
 545     if lorem
 546     {
 547         println!("ipsum!");
 548     }
 549     else
 550     {
 551         println!("dolor!");
 552     }
 553 }
 554 ```
 555
 556 #### `"ClosingNextLine"`:
 557
 558 ```rust
 559 fn main() {
 560     if lorem {
 561         println!("ipsum!");
 562     }
 563     else {
 564         println!("dolor!");
 565     }
 566 }
 567 ```
 568
 569 ## `disable_all_formatting`
 570
 571 Don't reformat anything
 572
 573 - **Default value**: `false`
 574 - **Possible values**: `true`, `false`
 575 - **Stable**: No
 576
 577 ## `error_on_line_overflow`
 578
 579 Error if unable to get all lines within `max_width`
 580
 581 - **Default value**: `true`
 582 - **Possible values**: `true`, `false`
 583 - **Stable**: No
 584
 585 See also [`max_width`](#max_width).
 586
 587 ## `error_on_line_overflow_comments`
 588
 589 Error if unable to get all comment lines within `comment_width`.
 590
 591 - **Default value**: `true`
 592 - **Possible values**: `true`, `false`
 593 - **Stable**: No
 594
 595 See also [`comment_width`](#comment_width).
 596
 597 ## `fn_args_density`
 598
 599 Argument density in functions
 600
 601 - **Default value**: `"Tall"`
 602 - **Possible values**: `"Compressed"`, `"Tall"`, `"Vertical"`
 603 - **Stable**: No
 604
 605 #### `"Tall"` (default):
 606
 607 ```rust
 608 trait Lorem {
 609     fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet);
 610
 611     fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet) {
 612         // body
 613     }
 614
 615     fn lorem(
 616         ipsum: Ipsum,
 617         dolor: Dolor,
 618         sit: Sit,
 619         amet: Amet,
 620         consectetur: Consectetur,
 621         adipiscing: Adipiscing,
 622         elit: Elit,
 623     );
 624
 625     fn lorem(
 626         ipsum: Ipsum,
 627         dolor: Dolor,
 628         sit: Sit,
 629         amet: Amet,
 630         consectetur: Consectetur,
 631         adipiscing: Adipiscing,
 632         elit: Elit,
 633     ) {
 634         // body
 635     }
 636 }
 637 ```
 638
 639 #### `"Compressed"`:
 640
 641 ```rust
 642 trait Lorem {
 643     fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet);
 644
 645     fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet) {
 646         // body
 647     }
 648
 649     fn lorem(
 650         ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur,
 651         adipiscing: Adipiscing, elit: Elit,
 652     );
 653
 654     fn lorem(
 655         ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur,
 656         adipiscing: Adipiscing, elit: Elit,
 657     ) {
 658         // body
 659     }
 660 }
 661 ```
 662
 663 #### `"Vertical"`:
 664
 665 ```rust
 666 trait Lorem {
 667     fn lorem(
 668         ipsum: Ipsum,
 669         dolor: Dolor,
 670         sit: Sit,
 671         amet: Amet,
 672     );
 673
 674     fn lorem(
 675         ipsum: Ipsum,
 676         dolor: Dolor,
 677         sit: Sit,
 678         amet: Amet,
 679     ) {
 680         // body
 681     }
 682
 683     fn lorem(
 684         ipsum: Ipsum,
 685         dolor: Dolor,
 686         sit: Sit,
 687         amet: Amet,
 688         consectetur: Consectetur,
 689         adipiscing: Adipiscing,
 690         elit: Elit,
 691     );
 692
 693     fn lorem(
 694         ipsum: Ipsum,
 695         dolor: Dolor,
 696         sit: Sit,
 697         amet: Amet,
 698         consectetur: Consectetur,
 699         adipiscing: Adipiscing,
 700         elit: Elit,
 701     ) {
 702         // body
 703     }
 704 }
 705 ```
 706
 707
 708 ## `brace_style`
 709
 710 Brace style for items
 711
 712 - **Default value**: `"SameLineWhere"`
 713 - **Possible values**: `"AlwaysNextLine"`, `"PreferSameLine"`, `"SameLineWhere"`
 714 - **Stable**: No
 715
 716 ### Functions
 717
 718 #### `"SameLineWhere"` (default):
 719
 720 ```rust
 721 fn lorem() {
 722     // body
 723 }
 724
 725 fn lorem(ipsum: usize) {
 726     // body
 727 }
 728
 729 fn lorem<T>(ipsum: T)
 730 where
 731     T: Add + Sub + Mul + Div,
 732 {
 733     // body
 734 }
 735 ```
 736
 737 #### `"AlwaysNextLine"`:
 738
 739 ```rust
 740 fn lorem()
 741 {
 742     // body
 743 }
 744
 745 fn lorem(ipsum: usize)
 746 {
 747     // body
 748 }
 749
 750 fn lorem<T>(ipsum: T)
 751 where
 752     T: Add + Sub + Mul + Div,
 753 {
 754     // body
 755 }
 756 ```
 757
 758 #### `"PreferSameLine"`:
 759
 760 ```rust
 761 fn lorem() {
 762     // body
 763 }
 764
 765 fn lorem(ipsum: usize) {
 766     // body
 767 }
 768
 769 fn lorem<T>(ipsum: T)
 770 where
 771     T: Add + Sub + Mul + Div, {
 772     // body
 773 }
 774 ```
 775
 776 ### Structs and enums
 777
 778 #### `"SameLineWhere"` (default):
 779
 780 ```rust
 781 struct Lorem {
 782     ipsum: bool,
 783 }
 784
 785 struct Dolor<T>
 786 where
 787     T: Eq,
 788 {
 789     sit: T,
 790 }
 791 ```
 792
 793 #### `"AlwaysNextLine"`:
 794
 795 ```rust
 796 struct Lorem
 797 {
 798     ipsum: bool,
 799 }
 800
 801 struct Dolor<T>
 802 where
 803     T: Eq,
 804 {
 805     sit: T,
 806 }
 807 ```
 808
 809 #### `"PreferSameLine"`:
 810
 811 ```rust
 812 struct Lorem {
 813     ipsum: bool,
 814 }
 815
 816 struct Dolor<T>
 817 where
 818     T: Eq, {
 819     sit: T,
 820 }
 821 ```
 822
 823
 824 ## `empty_item_single_line`
 825
 826 Put empty-body functions and impls on a single line
 827
 828 - **Default value**: `true`
 829 - **Possible values**: `true`, `false`
 830 - **Stable**: No
 831
 832 #### `true` (default):
 833
 834 ```rust
 835 fn lorem() {}
 836
 837 impl Lorem {}
 838 ```
 839
 840 #### `false`:
 841
 842 ```rust
 843 fn lorem() {
 844 }
 845
 846 impl Lorem {
 847 }
 848 ```
 849
 850 See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
 851
 852
 853 ## `fn_single_line`
 854
 855 Put single-expression functions on a single line
 856
 857 - **Default value**: `false`
 858 - **Possible values**: `true`, `false`
 859 - **Stable**: No
 860
 861 #### `false` (default):
 862
 863 ```rust
 864 fn lorem() -> usize {
 865     42
 866 }
 867
 868 fn lorem() -> usize {
 869     let ipsum = 42;
 870     ipsum
 871 }
 872 ```
 873
 874 #### `true`:
 875
 876 ```rust
 877 fn lorem() -> usize { 42 }
 878
 879 fn lorem() -> usize {
 880     let ipsum = 42;
 881     ipsum
 882 }
 883 ```
 884
 885 See also [`control_brace_style`](#control_brace_style).
 886
 887
 888 ## `where_single_line`
 889
 890 To force single line where layout
 891
 892 - **Default value**: `false`
 893 - **Possible values**: `true`, `false`
 894 - **Stable**: No
 895
 896 #### `false` (default):
 897
 898 ```rust
 899 impl<T> Lorem for T
 900 where
 901     Option<T>: Ipsum,
 902 {
 903     // body
 904 }
 905 ```
 906
 907 #### `true`:
 908
 909 ```rust
 910 impl<T> Lorem for T
 911 where Option<T>: Ipsum
 912 {
 913     // body
 914 }
 915 ```
 916
 917 See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
 918
 919
 920 ## `force_explicit_abi`
 921
 922 Always print the abi for extern items
 923
 924 - **Default value**: `true`
 925 - **Possible values**: `true`, `false`
 926 - **Stable**: Yes
 927
 928 **Note:** Non-"C" ABIs are always printed. If `false` then "C" is removed.
 929
 930 #### `true` (default):
 931
 932 ```rust
 933 extern "C" {
 934     pub static lorem: c_int;
 935 }
 936 ```
 937
 938 #### `false`:
 939
 940 ```rust
 941 extern {
 942     pub static lorem: c_int;
 943 }
 944 ```
 945
 946 ## `format_strings`
 947
 948 Format string literals where necessary
 949
 950 - **Default value**: `false`
 951 - **Possible values**: `true`, `false`
 952 - **Stable**: No
 953
 954 #### `false` (default):
 955
 956 ```rust
 957 fn main() {
 958     let lorem =
 959         "ipsum dolor sit amet consectetur adipiscing elit lorem ipsum dolor sit amet consectetur adipiscing";
 960 }
 961 ```
 962
 963 #### `true`:
 964
 965 ```rust
 966 fn main() {
 967     let lorem = "ipsum dolor sit amet consectetur adipiscing elit lorem ipsum dolor sit amet \
 968                  consectetur adipiscing";
 969 }
 970 ```
 971
 972 See also [`max_width`](#max_width).
 973
 974 ## `hard_tabs`
 975
 976 Use tab characters for indentation, spaces for alignment
 977
 978 - **Default value**: `false`
 979 - **Possible values**: `true`, `false`
 980 - **Stable**: Yes
 981
 982 #### `false` (default):
 983
 984 ```rust
 985 fn lorem() -> usize {
 986     42 // spaces before 42
 987 }
 988 ```
 989
 990 #### `true`:
 991
 992 ```rust
 993 fn lorem() -> usize {
 994         42 // tabs before 42
 995 }
 996 ```
 997
 998 See also: [`tab_spaces`](#tab_spaces).
 999
1000
1001 ## `imports_indent`
1002
1003 Indent style of imports
1004
1005 - **Default Value**: `"Visual"`
1006 - **Possible values**: `"Block"`, `"Visual"`
1007 - **Stable**: No
1008
1009 #### `"Visual"` (default):
1010
1011 ```rust
1012 use foo::{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy,
1013           zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz};
1014 ```
1015
1016 #### `"Block"`:
1017
1018 ```rust
1019 use foo::{
1020     xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy,
1021     zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz,
1022 };
1023 ```
1024
1025 See also: [`imports_layout`](#imports_layout).
1026
1027 ## `imports_layout`
1028
1029 Item layout inside a imports block
1030
1031 - **Default value**: "Mixed"
1032 - **Possible values**: "Horizontal", "HorizontalVertical", "Mixed", "Vertical"
1033 - **Stable**: No
1034
1035 #### `"Mixed"` (default):
1036
1037 ```rust
1038 use foo::{xxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyy, zzzzzzzzzzzzzzzzzz};
1039
1040 use foo::{aaaaaaaaaaaaaaaaaa, bbbbbbbbbbbbbbbbbb, cccccccccccccccccc, dddddddddddddddddd,
1041           eeeeeeeeeeeeeeeeee, ffffffffffffffffff};
1042 ```
1043
1044 #### `"Horizontal"`:
1045
1046 **Note**: This option forces all imports onto one line and may exceed `max_width`.
1047
1048 ```rust
1049 use foo::{xxx, yyy, zzz};
1050
1051 use foo::{aaa, bbb, ccc, ddd, eee, fff};
1052 ```
1053
1054 #### `"HorizontalVertical"`:
1055
1056 ```rust
1057 use foo::{xxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyy, zzzzzzzzzzzzzzzzzz};
1058
1059 use foo::{aaaaaaaaaaaaaaaaaa,
1060           bbbbbbbbbbbbbbbbbb,
1061           cccccccccccccccccc,
1062           dddddddddddddddddd,
1063           eeeeeeeeeeeeeeeeee,
1064           ffffffffffffffffff};
1065 ```
1066
1067 #### `"Vertical"`:
1068
1069 ```rust
1070 use foo::{xxx,
1071           yyy,
1072           zzz};
1073
1074 use foo::{aaa,
1075           bbb,
1076           ccc,
1077           ddd,
1078           eee,
1079           fff};
1080 ```
1081
1082
1083 ## `match_block_trailing_comma`
1084
1085 Put a trailing comma after a block based match arm (non-block arms are not affected)
1086
1087 - **Default value**: `false`
1088 - **Possible values**: `true`, `false`
1089 - **Stable**: No
1090
1091 #### `false` (default):
1092
1093 ```rust
1094 fn main() {
1095     match lorem {
1096         Lorem::Ipsum => {
1097             println!("ipsum");
1098         }
1099         Lorem::Dolor => println!("dolor"),
1100     }
1101 }
1102 ```
1103
1104 #### `true`:
1105
1106 ```rust
1107 fn main() {
1108     match lorem {
1109         Lorem::Ipsum => {
1110             println!("ipsum");
1111         },
1112         Lorem::Dolor => println!("dolor"),
1113     }
1114 }
1115 ```
1116
1117 See also: [`trailing_comma`](#trailing_comma), [`match_arm_blocks`](#match_arm_blocks).
1118
1119 ## `max_width`
1120
1121 Maximum width of each line
1122
1123 - **Default value**: `100`
1124 - **Possible values**: any positive integer
1125 - **Stable**: Yes
1126
1127 See also [`error_on_line_overflow`](#error_on_line_overflow).
1128
1129 ## `merge_derives`
1130
1131 Merge multiple derives into a single one.
1132
1133 - **Default value**: `true`
1134 - **Possible values**: `true`, `false`
1135 - **Stable**: Yes
1136
1137 #### `true` (default):
1138
1139 ```rust
1140 #[derive(Eq, PartialEq, Debug, Copy, Clone)]
1141 pub enum Foo {}
1142 ```
1143
1144 #### `false`:
1145
1146 ```rust
1147 #[derive(Eq, PartialEq)]
1148 #[derive(Debug)]
1149 #[derive(Copy, Clone)]
1150 pub enum Foo {}
1151 ```
1152
1153 ## `force_multiline_blocks`
1154
1155 Force multiline closure and match arm bodies to be wrapped in a block
1156
1157 - **Default value**: `false`
1158 - **Possible values**: `false`, `true`
1159 - **Stable**: No
1160
1161 #### `false` (default):
1162
1163 ```rust
1164 result.and_then(|maybe_value| match maybe_value {
1165     None => ...,
1166     Some(value) => ...,
1167 })
1168
1169 match lorem {
1170     None => if ipsum {
1171         println!("Hello World");
1172     },
1173     Some(dolor) => ...,
1174 }
1175 ```
1176
1177 #### `true`:
1178
1179 ```rust
1180
1181 result.and_then(|maybe_value| {
1182     match maybe_value {
1183         None => ...,
1184         Some(value) => ...,
1185     }
1186 })
1187
1188 match lorem {
1189     None => {
1190         if ipsum {
1191             println!("Hello World");
1192         }
1193     }
1194     Some(dolor) => ...,
1195 }
1196 ```
1197
1198
1199 ## `newline_style`
1200
1201 Unix or Windows line endings
1202
1203 - **Default value**: `"Unix"`
1204 - **Possible values**: `"Native"`, `"Unix"`, `"Windows"`
1205 - **Stable**: Yes
1206
1207 ## `normalize_comments`
1208
1209 Convert /* */ comments to // comments where possible
1210
1211 - **Default value**: `false`
1212 - **Possible values**: `true`, `false`
1213 - **Stable**: Yes
1214
1215 #### `false` (default):
1216
1217 ```rust
1218 // Lorem ipsum:
1219 fn dolor() -> usize {}
1220
1221 /* sit amet: */
1222 fn adipiscing() -> usize {}
1223 ```
1224
1225 #### `true`:
1226
1227 ```rust
1228 // Lorem ipsum:
1229 fn dolor() -> usize {}
1230
1231 // sit amet:
1232 fn adipiscing() -> usize {}
1233 ```
1234
1235 ## `reorder_imported_names`
1236
1237 Reorder lists of names in import statements alphabetically
1238
1239 - **Default value**: `false`
1240 - **Possible values**: `true`, `false`
1241 - **Stable**: No
1242
1243 #### `false` (default):
1244
1245 ```rust
1246 use super::{lorem, ipsum, dolor, sit};
1247 ```
1248
1249 #### `true`:
1250
1251 ```rust
1252 use super::{dolor, ipsum, lorem, sit};
1253 ```
1254
1255 See also [`reorder_imports`](#reorder_imports).
1256
1257 ## `reorder_imports`
1258
1259 Reorder import statements alphabetically
1260
1261 - **Default value**: `false`
1262 - **Possible values**: `true`, `false`
1263 - **Stable**: No
1264
1265 #### `false` (default):
1266
1267 ```rust
1268 use lorem;
1269 use ipsum;
1270 use dolor;
1271 use sit;
1272 ```
1273
1274 #### `true`:
1275
1276 ```rust
1277 use dolor;
1278 use ipsum;
1279 use lorem;
1280 use sit;
1281 ```
1282
1283 See also [`reorder_imported_names`](#reorder_imported_names), [`reorder_imports_in_group`](#reorder_imports_in_group).
1284
1285 ## `reorder_imports_in_group`
1286
1287 Reorder import statements in group
1288
1289 - **Default value**: `false`
1290 - **Possible values**: `true`, `false`
1291 - **Stable**: No
1292
1293 **Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
1294
1295 #### `false` (default):
1296
1297 ```rust
1298 use std::mem;
1299 use std::io;
1300
1301 use lorem;
1302 use ipsum;
1303 use dolor;
1304 use sit;
1305 ```
1306
1307 #### `true`:
1308
1309 ```rust
1310 use std::io;
1311 use std::mem;
1312
1313 use dolor;
1314 use ipsum;
1315 use lorem;
1316 use sit;
1317 ```
1318
1319 See also [`reorder_imports`](#reorder_imports).
1320
1321 ## `reorder_extern_crates`
1322
1323 Reorder `extern crate` statements alphabetically
1324
1325 - **Default value**: `true`
1326 - **Possible values**: `true`, `false`
1327 - **Stable**: No
1328
1329 #### `true` (default):
1330
1331 ```rust
1332 extern crate dolor;
1333 extern crate ipsum;
1334 extern crate lorem;
1335 extern crate sit;
1336 ```
1337
1338 #### `false`:
1339
1340 ```rust
1341 extern crate lorem;
1342 extern crate ipsum;
1343 extern crate dolor;
1344 extern crate sit;
1345 ```
1346
1347 See also [`reorder_extern_crates_in_group`](#reorder_extern_crates_in_group).
1348
1349 ## `reorder_extern_crates_in_group`
1350
1351 Reorder `extern crate` statements in group
1352
1353 - **Default value**: `true`
1354 - **Possible values**: `true`, `false`
1355 - **Stable**: No
1356
1357 **Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
1358
1359 #### `true` (default):
1360
1361 ```rust
1362 extern crate a;
1363 extern crate b;
1364
1365 extern crate dolor;
1366 extern crate ipsum;
1367 extern crate lorem;
1368 extern crate sit;
1369 ```
1370
1371 #### `false`:
1372
1373 ```rust
1374 extern crate b;
1375 extern crate a;
1376
1377 extern crate lorem;
1378 extern crate ipsum;
1379 extern crate dolor;
1380 extern crate sit;
1381 ```
1382
1383 See also [`reorder_extern_crates`](#reorder_extern_crates).
1384
1385 ## `report_todo`
1386
1387 Report `TODO` items in comments.
1388
1389 - **Default value**: `"Never"`
1390 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1391 - **Stable**: No
1392
1393 Warns about any comments containing `TODO` in them when set to `"Always"`. If
1394 it contains a `#X` (with `X` being a number) in parentheses following the
1395 `TODO`, `"Unnumbered"` will ignore it.
1396
1397 See also [`report_fixme`](#report_fixme).
1398
1399 ## `report_fixme`
1400
1401 Report `FIXME` items in comments.
1402
1403 - **Default value**: `"Never"`
1404 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1405 - **Stable**: No
1406
1407 Warns about any comments containing `FIXME` in them when set to `"Always"`. If
1408 it contains a `#X` (with `X` being a number) in parentheses following the
1409 `FIXME`, `"Unnumbered"` will ignore it.
1410
1411 See also [`report_todo`](#report_todo).
1412
1413
1414 ## `skip_children`
1415
1416 Don't reformat out of line modules
1417
1418 - **Default value**: `false`
1419 - **Possible values**: `true`, `false`
1420 - **Stable**: No
1421
1422 ## `space_after_colon`
1423
1424 Leave a space after the colon.
1425
1426 - **Default value**: `true`
1427 - **Possible values**: `true`, `false`
1428 - **Stable**: No
1429
1430 #### `true` (default):
1431
1432 ```rust
1433 fn lorem<T: Eq>(t: T) {
1434     let lorem: Dolor = Lorem {
1435         ipsum: dolor,
1436         sit: amet,
1437     };
1438 }
1439 ```
1440
1441 #### `false`:
1442
1443 ```rust
1444 fn lorem<T:Eq>(t:T) {
1445     let lorem:Dolor = Lorem {
1446         ipsum:dolor,
1447         sit:amet,
1448     };
1449 }
1450 ```
1451
1452 See also: [`space_before_colon`](#space_before_colon).
1453
1454 ## `space_before_colon`
1455
1456 Leave a space before the colon.
1457
1458 - **Default value**: `false`
1459 - **Possible values**: `true`, `false`
1460 - **Stable**: No
1461
1462 #### `false` (default):
1463
1464 ```rust
1465 fn lorem<T: Eq>(t: T) {
1466     let lorem: Dolor = Lorem {
1467         ipsum: dolor,
1468         sit: amet,
1469     };
1470 }
1471 ```
1472
1473 #### `true`:
1474
1475 ```rust
1476 fn lorem<T : Eq>(t : T) {
1477     let lorem : Dolor = Lorem {
1478         ipsum : dolor,
1479         sit : amet,
1480     };
1481 }
1482 ```
1483
1484 See also: [`space_after_colon`](#space_after_colon).
1485
1486 ## `struct_field_align_threshold`
1487
1488 The maximum diff of width between struct fields to be aligned with each other.
1489
1490 - **Default value** : 0
1491 - **Possible values**: any positive integer
1492 - **Stable**: No
1493
1494 #### `0` (default):
1495
1496 ```rust
1497 struct Foo {
1498     x: u32,
1499     yy: u32,
1500     zzz: u32,
1501 }
1502 ```
1503
1504 #### `20`:
1505
1506 ```rust
1507 struct Foo {
1508     x:   u32,
1509     yy:  u32,
1510     zzz: u32,
1511 }
1512 ```
1513
1514 ## `spaces_around_ranges`
1515
1516 Put spaces around the .., ..=, and ... range operators
1517
1518 - **Default value**: `false`
1519 - **Possible values**: `true`, `false`
1520 - **Stable**: No
1521
1522 #### `false` (default):
1523
1524 ```rust
1525 fn main() {
1526     let lorem = 0..10;
1527     let ipsum = 0..=10;
1528
1529     match lorem {
1530         1..5 => foo(),
1531         _ => bar,
1532     }
1533
1534     match lorem {
1535         1..=5 => foo(),
1536         _ => bar,
1537     }
1538
1539     match lorem {
1540         1...5 => foo(),
1541         _ => bar,
1542     }
1543 }
1544 ```
1545
1546 #### `true`:
1547
1548 ```rust
1549 fn main() {
1550     let lorem = 0 .. 10;
1551     let ipsum = 0 ..= 10;
1552
1553     match lorem {
1554         1 .. 5 => foo(),
1555         _ => bar,
1556     }
1557
1558     match lorem {
1559         1 ..= 5 => foo(),
1560         _ => bar,
1561     }
1562
1563     match lorem {
1564         1 ... 5 => foo(),
1565         _ => bar,
1566     }
1567 }
1568 ```
1569
1570 ## `spaces_within_parens_and_brackets`
1571
1572 Put spaces within non-empty generic arguments, parentheses, and square brackets
1573
1574 - **Default value**: `false`
1575 - **Possible values**: `true`, `false`
1576 - **Stable**: No
1577
1578 #### `false` (default):
1579
1580 ```rust
1581 // generic arguments
1582 fn lorem<T: Eq>(t: T) {
1583     // body
1584 }
1585
1586 // non-empty parentheses
1587 fn lorem<T: Eq>(t: T) {
1588     let lorem = (ipsum, dolor);
1589 }
1590
1591 // non-empty square brackets
1592 let lorem: [usize; 2] = [ipsum, dolor];
1593 ```
1594
1595 #### `true`:
1596
1597 ```rust
1598 // generic arguments
1599 fn lorem< T: Eq >(t: T) {
1600     // body
1601 }
1602
1603 // non-empty parentheses
1604 fn lorem<T: Eq>( t: T ) {
1605     let lorem = ( ipsum, dolor );
1606 }
1607
1608 // non-empty square brackets
1609 let lorem: [ usize; 2 ] = [ ipsum, dolor ];
1610 ```
1611
1612 ## `struct_lit_single_line`
1613
1614 Put small struct literals on a single line
1615
1616 - **Default value**: `true`
1617 - **Possible values**: `true`, `false`
1618 - **Stable**: No
1619
1620 #### `true` (default):
1621
1622 ```rust
1623 let lorem = Lorem { ipsum: dolor, sit: amet };
1624 ```
1625
1626 #### `false`:
1627
1628 ```rust
1629 let lorem = Lorem {
1630     ipsum: dolor,
1631     sit: amet,
1632 };
1633 ```
1634
1635 See also: [`indent_style`](#indent_style).
1636
1637
1638 ## `tab_spaces`
1639
1640 Number of spaces per tab
1641
1642 - **Default value**: `4`
1643 - **Possible values**: any positive integer
1644 - **Stable**: Yes
1645
1646 #### `4` (default):
1647
1648 ```rust
1649 fn lorem() {
1650     let ipsum = dolor();
1651     let sit = vec![
1652         "amet consectetur adipiscing elit."
1653     ];
1654 }
1655 ```
1656
1657 #### `2`:
1658
1659 ```rust
1660 fn lorem() {
1661   let ipsum = dolor();
1662   let sit = vec![
1663     "amet consectetur adipiscing elit."
1664   ];
1665 }
1666 ```
1667
1668 See also: [`hard_tabs`](#hard_tabs).
1669
1670
1671 ## `trailing_comma`
1672
1673 How to handle trailing commas for lists
1674
1675 - **Default value**: `"Vertical"`
1676 - **Possible values**: `"Always"`, `"Never"`, `"Vertical"`
1677 - **Stable**: No
1678
1679 #### `"Vertical"` (default):
1680
1681 ```rust
1682 let Lorem { ipsum, dolor, sit } = amet;
1683 let Lorem {
1684     ipsum,
1685     dolor,
1686     sit,
1687     amet,
1688     consectetur,
1689     adipiscing,
1690 } = elit;
1691 ```
1692
1693 #### `"Always"`:
1694
1695 ```rust
1696 let Lorem { ipsum, dolor, sit, } = amet;
1697 let Lorem {
1698     ipsum,
1699     dolor,
1700     sit,
1701     amet,
1702     consectetur,
1703     adipiscing,
1704 } = elit;
1705 ```
1706
1707 #### `"Never"`:
1708
1709 ```rust
1710 let Lorem { ipsum, dolor, sit } = amet;
1711 let Lorem {
1712     ipsum,
1713     dolor,
1714     sit,
1715     amet,
1716     consectetur,
1717     adipiscing
1718 } = elit;
1719 ```
1720
1721 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1722
1723 ## `trailing_semicolon`
1724
1725 Add trailing semicolon after break, continue and return
1726
1727 - **Default value**: `true`
1728 - **Possible values**: `true`, `false`
1729 - **Stable**: No
1730
1731 #### `true` (default):
1732 ```rust
1733 fn foo() -> usize {
1734     return 0;
1735 }
1736 ```
1737
1738 #### `false`:
1739 ```rust
1740 fn foo() -> usize {
1741     return 0
1742 }
1743 ```
1744
1745 ## `type_punctuation_density`
1746
1747 Determines if `+` or `=` are wrapped in spaces in the punctuation of types
1748
1749 - **Default value**: `"Wide"`
1750 - **Possible values**: `"Compressed"`, `"Wide"`
1751 - **Stable**: No
1752
1753 #### `"Wide"` (default):
1754
1755 ```rust
1756 fn lorem<Ipsum: Dolor + Sit = Amet>() {
1757         // body
1758 }
1759 ```
1760
1761 #### `"Compressed"`:
1762
1763 ```rust
1764 fn lorem<Ipsum: Dolor+Sit=Amet>() {
1765         // body
1766 }
1767 ```
1768
1769 ## `use_try_shorthand`
1770
1771 Replace uses of the try! macro by the ? shorthand
1772
1773 - **Default value**: `false`
1774 - **Possible values**: `true`, `false`
1775 - **Stable**: No
1776
1777 #### `false` (default):
1778
1779 ```rust
1780 let lorem = try!(ipsum.map(|dolor|dolor.sit()));
1781 ```
1782
1783 #### `true`:
1784
1785 ```rust
1786 let lorem = ipsum.map(|dolor| dolor.sit())?;
1787 ```
1788
1789
1790 ## `wrap_comments`
1791
1792 Break comments to fit on the line
1793
1794 - **Default value**: `false`
1795 - **Possible values**: `true`, `false`
1796 - **Stable**: Yes
1797
1798 #### `false` (default):
1799
1800 ```rust
1801 // Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
1802 ```
1803
1804 #### `true`:
1805
1806 ```rust
1807 // Lorem ipsum dolor sit amet, consectetur adipiscing elit,
1808 // sed do eiusmod tempor incididunt ut labore et dolore
1809 // magna aliqua. Ut enim ad minim veniam, quis nostrud
1810 // exercitation ullamco laboris nisi ut aliquip ex ea
1811 // commodo consequat.
1812 ```
1813
1814 ## `match_arm_blocks`
1815
1816 Wrap the body of arms in blocks when it does not fit on the same line with the pattern of arms
1817
1818 - **Default value**: `true`
1819 - **Possible values**: `true`, `false`
1820 - **Stable**: No
1821
1822 #### `true` (default):
1823
1824 ```rust
1825 match lorem {
1826     true => {
1827         foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x)
1828     }
1829     false => println!("{}", sit),
1830 }
1831 ```
1832
1833 #### `false`:
1834
1835 ```rust
1836 match lorem {
1837     true =>
1838         foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x),
1839     false => println!("{}", sit),
1840 }
1841 ```
1842
1843 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1844
1845 ## `write_mode`
1846
1847 What Write Mode to use when none is supplied: Replace, Overwrite, Display, Diff, Coverage
1848
1849 - **Default value**: `"Overwrite"`
1850 - **Possible values**: `"Checkstyle"`, `"Coverage"`, `"Diff"`, `"Display"`, `"Overwrite"`, `"Plain"`, `"Replace"`
1851 - **Stable**: No
1852
1853 ## `blank_lines_upper_bound`
1854
1855 Maximum number of blank lines which can be put between items. If more than this number of consecutive empty
1856 lines are found, they are trimmed down to match this integer.
1857
1858 - **Default value**: `1`
1859 - **Possible values**: *unsigned integer*
1860 - **Stable**: No
1861
1862 ### Example
1863 Original Code:
1864
1865 ```rust
1866 fn foo() {
1867     println!("a");
1868 }
1869
1870
1871
1872 fn bar() {
1873     println!("b");
1874
1875
1876     println!("c");
1877 }
1878 ```
1879
1880 #### `1` (default):
1881 ```rust
1882 fn foo() {
1883     println!("a");
1884 }
1885
1886 fn bar() {
1887     println!("b");
1888
1889     println!("c");
1890 }
1891 ```
1892
1893 #### `2` (default):
1894 ```rust
1895 fn foo() {
1896     println!("a");
1897 }
1898
1899
1900 fn bar() {
1901     println!("b");
1902
1903
1904     println!("c");
1905 }
1906 ```
1907
1908 See also: [`blank_lines_lower_bound`](#blank_lines_lower_bound)
1909
1910 ## `blank_lines_lower_bound`
1911
1912 Minimum number of blank lines which must be put between items. If two items have fewer blank lines between
1913 them, additional blank lines are inserted.
1914
1915 - **Default value**: `0`
1916 - **Possible values**: *unsigned integer*
1917 - **Stable**: No
1918
1919 ### Example
1920 Original Code (rustfmt will not change it with the default value of `0`):
1921
1922 ```rust
1923 fn foo() {
1924     println!("a");
1925 }
1926 fn bar() {
1927     println!("b");
1928     println!("c");
1929 }
1930 ```
1931
1932 #### `1`
1933 ```rust
1934 fn foo() {
1935
1936     println!("a");
1937 }
1938
1939 fn bar() {
1940
1941     println!("b");
1942
1943     println!("c");
1944 }
1945 ```