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::{xxx, yyy, zzz};
1058
1059 use foo::{aaa,
1060           bbb,
1061           ccc,
1062           ddd,
1063           eee,
1064           fff};
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 match lorem {
1095     Lorem::Ipsum => {
1096         println!("ipsum");
1097     }
1098     Lorem::Dolor => println!("dolor"),
1099 }
1100 ```
1101
1102 #### `true`:
1103
1104 ```rust
1105 match lorem {
1106     Lorem::Ipsum => {
1107         println!("ipsum");
1108     },
1109     Lorem::Dolor => println!("dolor"),
1110 }
1111 ```
1112
1113 See also: [`trailing_comma`](#trailing_comma), [`match_arm_blocks`](#match_arm_blocks).
1114
1115 ## `max_width`
1116
1117 Maximum width of each line
1118
1119 - **Default value**: `100`
1120 - **Possible values**: any positive integer
1121 - **Stable**: Yes
1122
1123 See also [`error_on_line_overflow`](#error_on_line_overflow).
1124
1125 ## `merge_derives`
1126
1127 Merge multiple derives into a single one.
1128
1129 - **Default value**: `true`
1130 - **Possible values**: `true`, `false`
1131 - **Stable**: Yes
1132
1133 #### `true` (default):
1134
1135 ```rust
1136 #[derive(Eq, PartialEq, Debug, Copy, Clone)]
1137 pub enum Foo {}
1138 ```
1139
1140 #### `false`:
1141
1142 ```rust
1143 #[derive(Eq, PartialEq)]
1144 #[derive(Debug)]
1145 #[derive(Copy, Clone)]
1146 pub enum Foo {}
1147 ```
1148
1149 ## `force_multiline_blocks`
1150
1151 Force multiline closure and match arm bodies to be wrapped in a block
1152
1153 - **Default value**: `false`
1154 - **Possible values**: `false`, `true`
1155 - **Stable**: No
1156
1157 #### `false` (default):
1158
1159 ```rust
1160 result.and_then(|maybe_value| match maybe_value {
1161     None => ...,
1162     Some(value) => ...,
1163 })
1164
1165 match lorem {
1166     None => if ipsum {
1167         println!("Hello World");
1168     },
1169     Some(dolor) => ...,
1170 }
1171 ```
1172
1173 #### `true`:
1174
1175 ```rust
1176
1177 result.and_then(|maybe_value| {
1178     match maybe_value {
1179         None => ...,
1180         Some(value) => ...,
1181     }
1182 })
1183
1184 match lorem {
1185     None => {
1186         if ipsum {
1187             println!("Hello World");
1188         }
1189     }
1190     Some(dolor) => ...,
1191 }
1192 ```
1193
1194
1195 ## `newline_style`
1196
1197 Unix or Windows line endings
1198
1199 - **Default value**: `"Unix"`
1200 - **Possible values**: `"Native"`, `"Unix"`, `"Windows"`
1201 - **Stable**: Yes
1202
1203 ## `normalize_comments`
1204
1205 Convert /* */ comments to // comments where possible
1206
1207 - **Default value**: `false`
1208 - **Possible values**: `true`, `false`
1209 - **Stable**: Yes
1210
1211 #### `false` (default):
1212
1213 ```rust
1214 // Lorem ipsum:
1215 fn dolor() -> usize {}
1216
1217 /* sit amet: */
1218 fn adipiscing() -> usize {}
1219 ```
1220
1221 #### `true`:
1222
1223 ```rust
1224 // Lorem ipsum:
1225 fn dolor() -> usize {}
1226
1227 // sit amet:
1228 fn adipiscing() -> usize {}
1229 ```
1230
1231 ## `reorder_imported_names`
1232
1233 Reorder lists of names in import statements alphabetically
1234
1235 - **Default value**: `false`
1236 - **Possible values**: `true`, `false`
1237 - **Stable**: No
1238
1239 #### `false` (default):
1240
1241 ```rust
1242 use super::{lorem, ipsum, dolor, sit};
1243 ```
1244
1245 #### `true`:
1246
1247 ```rust
1248 use super::{dolor, ipsum, lorem, sit};
1249 ```
1250
1251 See also [`reorder_imports`](#reorder_imports).
1252
1253 ## `reorder_imports`
1254
1255 Reorder import statements alphabetically
1256
1257 - **Default value**: `false`
1258 - **Possible values**: `true`, `false`
1259 - **Stable**: No
1260
1261 #### `false` (default):
1262
1263 ```rust
1264 use lorem;
1265 use ipsum;
1266 use dolor;
1267 use sit;
1268 ```
1269
1270 #### `true`:
1271
1272 ```rust
1273 use dolor;
1274 use ipsum;
1275 use lorem;
1276 use sit;
1277 ```
1278
1279 See also [`reorder_imported_names`](#reorder_imported_names), [`reorder_imports_in_group`](#reorder_imports_in_group).
1280
1281 ## `reorder_imports_in_group`
1282
1283 Reorder import statements in group
1284
1285 - **Default value**: `false`
1286 - **Possible values**: `true`, `false`
1287 - **Stable**: No
1288
1289 **Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
1290
1291 #### `false` (default):
1292
1293 ```rust
1294 use std::mem;
1295 use std::io;
1296
1297 use lorem;
1298 use ipsum;
1299 use dolor;
1300 use sit;
1301 ```
1302
1303 #### `true`:
1304
1305 ```rust
1306 use std::io;
1307 use std::mem;
1308
1309 use dolor;
1310 use ipsum;
1311 use lorem;
1312 use sit;
1313 ```
1314
1315 See also [`reorder_imports`](#reorder_imports).
1316
1317 ## `reorder_extern_crates`
1318
1319 Reorder `extern crate` statements alphabetically
1320
1321 - **Default value**: `true`
1322 - **Possible values**: `true`, `false`
1323 - **Stable**: No
1324
1325 #### `true` (default):
1326
1327 ```rust
1328 extern crate dolor;
1329 extern crate ipsum;
1330 extern crate lorem;
1331 extern crate sit;
1332 ```
1333
1334 #### `false`:
1335
1336 ```rust
1337 extern crate lorem;
1338 extern crate ipsum;
1339 extern crate dolor;
1340 extern crate sit;
1341 ```
1342
1343 See also [`reorder_extern_crates_in_group`](#reorder_extern_crates_in_group).
1344
1345 ## `reorder_extern_crates_in_group`
1346
1347 Reorder `extern crate` statements in group
1348
1349 - **Default value**: `true`
1350 - **Possible values**: `true`, `false`
1351 - **Stable**: No
1352
1353 **Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
1354
1355 #### `true` (default):
1356
1357 ```rust
1358 extern crate a;
1359 extern crate b;
1360
1361 extern crate dolor;
1362 extern crate ipsum;
1363 extern crate lorem;
1364 extern crate sit;
1365 ```
1366
1367 #### `false`:
1368
1369 ```rust
1370 extern crate b;
1371 extern crate a;
1372
1373 extern crate lorem;
1374 extern crate ipsum;
1375 extern crate dolor;
1376 extern crate sit;
1377 ```
1378
1379 See also [`reorder_extern_crates`](#reorder_extern_crates).
1380
1381 ## `report_todo`
1382
1383 Report `TODO` items in comments.
1384
1385 - **Default value**: `"Never"`
1386 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1387 - **Stable**: No
1388
1389 Warns about any comments containing `TODO` in them when set to `"Always"`. If
1390 it contains a `#X` (with `X` being a number) in parentheses following the
1391 `TODO`, `"Unnumbered"` will ignore it.
1392
1393 See also [`report_fixme`](#report_fixme).
1394
1395 ## `report_fixme`
1396
1397 Report `FIXME` items in comments.
1398
1399 - **Default value**: `"Never"`
1400 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1401 - **Stable**: No
1402
1403 Warns about any comments containing `FIXME` in them when set to `"Always"`. If
1404 it contains a `#X` (with `X` being a number) in parentheses following the
1405 `FIXME`, `"Unnumbered"` will ignore it.
1406
1407 See also [`report_todo`](#report_todo).
1408
1409
1410 ## `skip_children`
1411
1412 Don't reformat out of line modules
1413
1414 - **Default value**: `false`
1415 - **Possible values**: `true`, `false`
1416 - **Stable**: No
1417
1418 ## `space_after_colon`
1419
1420 Leave a space after the colon.
1421
1422 - **Default value**: `true`
1423 - **Possible values**: `true`, `false`
1424 - **Stable**: No
1425
1426 #### `true` (default):
1427
1428 ```rust
1429 fn lorem<T: Eq>(t: T) {
1430     let lorem: Dolor = Lorem {
1431         ipsum: dolor,
1432         sit: amet,
1433     };
1434 }
1435 ```
1436
1437 #### `false`:
1438
1439 ```rust
1440 fn lorem<T:Eq>(t:T) {
1441     let lorem:Dolor = Lorem {
1442         ipsum:dolor,
1443         sit:amet,
1444     };
1445 }
1446 ```
1447
1448 See also: [`space_before_colon`](#space_before_colon).
1449
1450 ## `space_before_colon`
1451
1452 Leave a space before the colon.
1453
1454 - **Default value**: `false`
1455 - **Possible values**: `true`, `false`
1456 - **Stable**: No
1457
1458 #### `false` (default):
1459
1460 ```rust
1461 fn lorem<T: Eq>(t: T) {
1462     let lorem: Dolor = Lorem {
1463         ipsum: dolor,
1464         sit: amet,
1465     };
1466 }
1467 ```
1468
1469 #### `true`:
1470
1471 ```rust
1472 fn lorem<T : Eq>(t : T) {
1473     let lorem : Dolor = Lorem {
1474         ipsum : dolor,
1475         sit : amet,
1476     };
1477 }
1478 ```
1479
1480 See also: [`space_after_colon`](#space_after_colon).
1481
1482 ## `struct_field_align_threshold`
1483
1484 The maximum diff of width between struct fields to be aligned with each other.
1485
1486 - **Default value** : 0
1487 - **Possible values**: any positive integer
1488 - **Stable**: No
1489
1490 #### `0` (default):
1491
1492 ```rust
1493 struct Foo {
1494     x: u32,
1495     yy: u32,
1496     zzz: u32,
1497 }
1498 ```
1499
1500 #### `20`:
1501
1502 ```rust
1503 struct Foo {
1504     x:   u32,
1505     yy:  u32,
1506     zzz: u32,
1507 }
1508 ```
1509
1510 ## `spaces_around_ranges`
1511
1512 Put spaces around the .. and ... range operators
1513
1514 - **Default value**: `false`
1515 - **Possible values**: `true`, `false`
1516 - **Stable**: No
1517
1518 #### `false` (default):
1519
1520 ```rust
1521 let lorem = 0..10;
1522 ```
1523
1524 #### `true`:
1525
1526 ```rust
1527 let lorem = 0 .. 10;
1528 ```
1529
1530 ## `spaces_within_parens_and_brackets`
1531
1532 Put spaces within non-empty generic arguments, parentheses, and square brackets
1533
1534 - **Default value**: `false`
1535 - **Possible values**: `true`, `false`
1536 - **Stable**: No
1537
1538 #### `false` (default):
1539
1540 ```rust
1541 // generic arguments
1542 fn lorem<T: Eq>(t: T) {
1543     // body
1544 }
1545
1546 // non-empty parentheses
1547 fn lorem<T: Eq>(t: T) {
1548     let lorem = (ipsum, dolor);
1549 }
1550
1551 // non-empty square brackets
1552 let lorem: [usize; 2] = [ipsum, dolor];
1553 ```
1554
1555 #### `true`:
1556
1557 ```rust
1558 // generic arguments
1559 fn lorem< T: Eq >(t: T) {
1560     // body
1561 }
1562
1563 // non-empty parentheses
1564 fn lorem<T: Eq>( t: T ) {
1565     let lorem = ( ipsum, dolor );
1566 }
1567
1568 // non-empty square brackets
1569 let lorem: [ usize; 2 ] = [ ipsum, dolor ];
1570 ```
1571
1572 ## `struct_lit_single_line`
1573
1574 Put small struct literals on a single line
1575
1576 - **Default value**: `true`
1577 - **Possible values**: `true`, `false`
1578 - **Stable**: No
1579
1580 #### `true` (default):
1581
1582 ```rust
1583 let lorem = Lorem { ipsum: dolor, sit: amet };
1584 ```
1585
1586 #### `false`:
1587
1588 ```rust
1589 let lorem = Lorem {
1590     ipsum: dolor,
1591     sit: amet,
1592 };
1593 ```
1594
1595 See also: [`indent_style`](#indent_style).
1596
1597
1598 ## `tab_spaces`
1599
1600 Number of spaces per tab
1601
1602 - **Default value**: `4`
1603 - **Possible values**: any positive integer
1604 - **Stable**: Yes
1605
1606 #### `4` (default):
1607
1608 ```rust
1609 fn lorem() {
1610     let ipsum = dolor();
1611     let sit = vec![
1612         "amet consectetur adipiscing elit."
1613     ];
1614 }
1615 ```
1616
1617 #### `2`:
1618
1619 ```rust
1620 fn lorem() {
1621   let ipsum = dolor();
1622   let sit = vec![
1623     "amet consectetur adipiscing elit."
1624   ];
1625 }
1626 ```
1627
1628 See also: [`hard_tabs`](#hard_tabs).
1629
1630
1631 ## `trailing_comma`
1632
1633 How to handle trailing commas for lists
1634
1635 - **Default value**: `"Vertical"`
1636 - **Possible values**: `"Always"`, `"Never"`, `"Vertical"`
1637 - **Stable**: No
1638
1639 #### `"Vertical"` (default):
1640
1641 ```rust
1642 let Lorem { ipsum, dolor, sit } = amet;
1643 let Lorem {
1644     ipsum,
1645     dolor,
1646     sit,
1647     amet,
1648     consectetur,
1649     adipiscing,
1650 } = elit;
1651 ```
1652
1653 #### `"Always"`:
1654
1655 ```rust
1656 let Lorem { ipsum, dolor, sit, } = amet;
1657 let Lorem {
1658     ipsum,
1659     dolor,
1660     sit,
1661     amet,
1662     consectetur,
1663     adipiscing,
1664 } = elit;
1665 ```
1666
1667 #### `"Never"`:
1668
1669 ```rust
1670 let Lorem { ipsum, dolor, sit } = amet;
1671 let Lorem {
1672     ipsum,
1673     dolor,
1674     sit,
1675     amet,
1676     consectetur,
1677     adipiscing
1678 } = elit;
1679 ```
1680
1681 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1682
1683 ## `trailing_semicolon`
1684
1685 Add trailing semicolon after break, continue and return
1686
1687 - **Default value**: `true`
1688 - **Possible values**: `true`, `false`
1689 - **Stable**: No
1690
1691 #### `true` (default):
1692 ```rust
1693 fn foo() -> usize {
1694     return 0;
1695 }
1696 ```
1697
1698 #### `false`:
1699 ```rust
1700 fn foo() -> usize {
1701     return 0
1702 }
1703 ```
1704
1705 ## `type_punctuation_density`
1706
1707 Determines if `+` or `=` are wrapped in spaces in the punctuation of types
1708
1709 - **Default value**: `"Wide"`
1710 - **Possible values**: `"Compressed"`, `"Wide"`
1711 - **Stable**: No
1712
1713 #### `"Wide"` (default):
1714
1715 ```rust
1716 fn lorem<Ipsum: Dolor + Sit = Amet>() {
1717         // body
1718 }
1719 ```
1720
1721 #### `"Compressed"`:
1722
1723 ```rust
1724 fn lorem<Ipsum: Dolor+Sit=Amet>() {
1725         // body
1726 }
1727 ```
1728
1729 ## `use_try_shorthand`
1730
1731 Replace uses of the try! macro by the ? shorthand
1732
1733 - **Default value**: `false`
1734 - **Possible values**: `true`, `false`
1735 - **Stable**: No
1736
1737 #### `false` (default):
1738
1739 ```rust
1740 let lorem = try!(ipsum.map(|dolor|dolor.sit()));
1741 ```
1742
1743 #### `true`:
1744
1745 ```rust
1746 let lorem = ipsum.map(|dolor| dolor.sit())?;
1747 ```
1748
1749
1750 ## `wrap_comments`
1751
1752 Break comments to fit on the line
1753
1754 - **Default value**: `false`
1755 - **Possible values**: `true`, `false`
1756 - **Stable**: Yes
1757
1758 #### `false` (default):
1759
1760 ```rust
1761 // 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.
1762 ```
1763
1764 #### `true`:
1765
1766 ```rust
1767 // Lorem ipsum dolor sit amet, consectetur adipiscing elit,
1768 // sed do eiusmod tempor incididunt ut labore et dolore
1769 // magna aliqua. Ut enim ad minim veniam, quis nostrud
1770 // exercitation ullamco laboris nisi ut aliquip ex ea
1771 // commodo consequat.
1772 ```
1773
1774 ## `match_arm_blocks`
1775
1776 Wrap the body of arms in blocks when it does not fit on the same line with the pattern of arms
1777
1778 - **Default value**: `true`
1779 - **Possible values**: `true`, `false`
1780 - **Stable**: No
1781
1782 #### `true` (default):
1783
1784 ```rust
1785 match lorem {
1786     true => {
1787         foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x)
1788     }
1789     false => println!("{}", sit),
1790 }
1791 ```
1792
1793 #### `false`:
1794
1795 ```rust
1796 match lorem {
1797     true =>
1798         foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x),
1799     false => println!("{}", sit),
1800 }
1801 ```
1802
1803 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1804
1805 ## `write_mode`
1806
1807 What Write Mode to use when none is supplied: Replace, Overwrite, Display, Diff, Coverage
1808
1809 - **Default value**: `"Overwrite"`
1810 - **Possible values**: `"Checkstyle"`, `"Coverage"`, `"Diff"`, `"Display"`, `"Overwrite"`, `"Plain"`, `"Replace"`
1811 - **Stable**: No
1812
1813 ## `blank_lines_upper_bound`
1814
1815 Maximum number of blank lines which can be put between items. If more than this number of consecutive empty
1816 lines are found, they are trimmed down to match this integer.
1817
1818 - **Default value**: `1`
1819 - **Possible values**: *unsigned integer*
1820 - **Stable**: No
1821
1822 ### Example
1823 Original Code:
1824
1825 ```rust
1826 fn foo() {
1827     println!("a");
1828 }
1829
1830
1831
1832 fn bar() {
1833     println!("b");
1834
1835
1836     println!("c");
1837 }
1838 ```
1839
1840 #### `1` (default):
1841 ```rust
1842 fn foo() {
1843     println!("a");
1844 }
1845
1846 fn bar() {
1847     println!("b");
1848
1849     println!("c");
1850 }
1851 ```
1852
1853 #### `2` (default):
1854 ```rust
1855 fn foo() {
1856     println!("a");
1857 }
1858
1859
1860 fn bar() {
1861     println!("b");
1862
1863
1864     println!("c");
1865 }
1866 ```
1867
1868 See also: [`blank_lines_lower_bound`](#blank_lines_lower_bound)
1869
1870 ## `blank_lines_lower_bound`
1871
1872 Minimum number of blank lines which must be put between items. If two items have fewer blank lines between
1873 them, additional blank lines are inserted.
1874
1875 - **Default value**: `0`
1876 - **Possible values**: *unsigned integer*
1877 - **Stable**: No
1878
1879 ### Example
1880 Original Code (rustfmt will not change it with the default value of `0`):
1881
1882 ```rust
1883 fn foo() {
1884     println!("a");
1885 }
1886 fn bar() {
1887     println!("b");
1888     println!("c");
1889 }
1890 ```
1891
1892 #### `1`
1893 ```rust
1894 fn foo() {
1895
1896     println!("a");
1897 }
1898
1899 fn bar() {
1900
1901     println!("b");
1902
1903     println!("c");
1904 }
1905 ```