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