.config/coc/extensions/coc-go-data/tools/pkg/mod/mvdan.cc/gofumpt@v0.0.0-20200802201014-ab5a8192947d/README.md

   1 # gofumpt
   2
   3         GO111MODULE=on go get mvdan.cc/gofumpt
   4
   5 Enforce a stricter format than `gofmt`, while being backwards compatible. That
   6 is, `gofumpt` is happy with a subset of the formats that `gofmt` is happy with.
   7
   8 The tool is a modified fork of `gofmt`, so it can be used as a drop-in
   9 replacement. Running `gofmt` after `gofumpt` should be a no-op.
  10
  11 A drop-in replacement for `goimports` is also available:
  12
  13         GO111MODULE=on go get mvdan.cc/gofumpt/gofumports
  14
  15 Most of the Go source files in this repository belong to the Go project.
  16 The added formatting rules are in the `format` package.
  17
  18 ### Added rules
  19
  20 No empty lines at the beginning or end of a function
  21
  22 <details><summary><i>example</i></summary>
  23
  24 ```
  25 func foo() {
  26         println("bar")
  27
  28 }
  29 ```
  30
  31 ```
  32 func foo() {
  33         println("bar")
  34 }
  35 ```
  36
  37 </details>
  38
  39 No empty lines around a lone statement (or comment) in a block
  40
  41 <details><summary><i>example</i></summary>
  42
  43 ```
  44 if err != nil {
  45
  46         return err
  47 }
  48 ```
  49
  50 ```
  51 if err != nil {
  52         return err
  53 }
  54 ```
  55
  56 </details>
  57
  58 No empty lines before a simple error check
  59
  60 <details><summary><i>example</i></summary>
  61
  62 ```
  63 foo, err := processFoo()
  64
  65 if err != nil {
  66         return err
  67 }
  68 ```
  69
  70 ```
  71 foo, err := processFoo()
  72 if err != nil {
  73         return err
  74 }
  75 ```
  76
  77 </details>
  78
  79 Composite literals should use newlines consistently
  80
  81 <details><summary><i>example</i></summary>
  82
  83 ```
  84 // A newline before or after an element requires newlines for the opening and
  85 // closing braces.
  86 var ints = []int{1, 2,
  87         3, 4}
  88
  89 // A newline between consecutive elements requires a newline between all
  90 // elements.
  91 var matrix = [][]int{
  92         {1},
  93         {2}, {
  94                 3,
  95         },
  96 }
  97 ```
  98
  99 ```
 100 var ints = []int{
 101         1, 2,
 102         3, 4,
 103 }
 104
 105 var matrix = [][]int{
 106         {1},
 107         {2},
 108         {
 109                 3,
 110         },
 111 }
 112 ```
 113
 114 </details>
 115
 116 `std` imports must be in a separate group at the top
 117
 118 <details><summary><i>example</i></summary>
 119
 120 ```
 121 import (
 122         "foo.com/bar"
 123
 124         "io"
 125
 126         "io/ioutil"
 127 )
 128 ```
 129
 130 ```
 131 import (
 132         "io"
 133         "io/ioutil"
 134
 135         "foo.com/bar"
 136 )
 137 ```
 138
 139 </details>
 140
 141 Short case clauses should take a single line
 142
 143 <details><summary><i>example</i></summary>
 144
 145 ```
 146 switch c {
 147 case 'a', 'b',
 148         'c', 'd':
 149 }
 150 ```
 151
 152 ```
 153 switch c {
 154 case 'a', 'b', 'c', 'd':
 155 }
 156 ```
 157
 158 </details>
 159
 160 Multiline top-level declarations must be separated by empty lines
 161
 162 <details><summary><i>example</i></summary>
 163
 164 ```
 165 func foo() {
 166         println("multiline foo")
 167 }
 168 func bar() {
 169         println("multiline bar")
 170 }
 171 ```
 172
 173 ```
 174 func foo() {
 175         println("multiline foo")
 176 }
 177
 178 func bar() {
 179         println("multiline bar")
 180 }
 181 ```
 182
 183 </details>
 184
 185 Single var declarations should not be grouped with parentheses
 186
 187 <details><summary><i>example</i></summary>
 188
 189 ```
 190 var (
 191         foo = "bar"
 192 )
 193 ```
 194
 195 ```
 196 var foo = "bar"
 197 ```
 198
 199 </details>
 200
 201 Contiguous top-level declarations should be grouped together
 202
 203 <details><summary><i>example</i></summary>
 204
 205 ```
 206 var nicer = "x"
 207 var with = "y"
 208 var alignment = "z"
 209 ```
 210
 211 ```
 212 var (
 213         nicer     = "x"
 214         with      = "y"
 215         alignment = "z"
 216 )
 217 ```
 218
 219 </details>
 220
 221
 222 Simple var-declaration statements should use short assignments
 223
 224 <details><summary><i>example</i></summary>
 225
 226 ```
 227 var s = "somestring"
 228 ```
 229
 230 ```
 231 s := "somestring"
 232 ```
 233
 234 </details>
 235
 236
 237 The `-s` code simplification flag is enabled by default
 238
 239 <details><summary><i>example</i></summary>
 240
 241 ```
 242 var _ = [][]int{[]int{1}}
 243 ```
 244
 245 ```
 246 var _ = [][]int{{1}}
 247 ```
 248
 249 </details>
 250
 251
 252 Octal integer literals should use the `0o` prefix on modules using Go 1.13 and later
 253
 254 <details><summary><i>example</i></summary>
 255
 256 ```
 257 const perm = 0755
 258 ```
 259
 260 ```
 261 const perm = 0o755
 262 ```
 263
 264 </details>
 265
 266 Comments which aren't Go directives should start with a whitespace
 267
 268 <details><summary><i>example</i></summary>
 269
 270 ```
 271 //go:noinline
 272
 273 //Foo is awesome.
 274 func Foo() {}
 275 ```
 276
 277 ```
 278 //go:noinline
 279
 280 // Foo is awesome.
 281 func Foo() {}
 282 ```
 283
 284 </details>
 285
 286 #### Extra rules behind `-extra`
 287
 288 Adjacent parameters with the same type should be grouped together
 289
 290 <details><summary><i>example</i></summary>
 291
 292 ```
 293 func Foo(bar string, baz string) {}
 294 ```
 295
 296 ```
 297 func Foo(bar, baz string) {}
 298 ```
 299
 300 </details>
 301
 302 ### Installation
 303
 304 `gofumpt` is a replacement for `gofmt`, so you can simply `go get` it as
 305 described at the top of this README and use it.
 306
 307 Alternatively, to use the tool with VS Code, add these settings:
 308
 309 ```
 310 "go.formatTool": "goimports",
 311 "go.alternateTools": {
 312         "goimports": "gofumports",
 313 },
 314 "go.languageServerExperimentalFeatures": {
 315         "format": false
 316 }
 317 ```
 318
 319 You can use `gofmt` instead of `goimports` and `gofumpt` instead of `gofumports`
 320 if you don't need auto-importing on-save.
 321
 322 ### Roadmap
 323
 324 This tool is a place to experiment. In the long term, the features that work
 325 well might be proposed for `gofmt` itself.
 326
 327 The tool is also compatible with `gofmt` and is aimed to be stable, so you can
 328 rely on it for your code as long as you pin a version of it.
 329
 330 ### License
 331
 332 Note that much of the code is copied from Go's `gofmt` and `goimports` commands.
 333 You can tell which files originate from the Go repository from their copyright
 334 headers. Their license file is `LICENSE.google`.
 335
 336 `gofumpt`'s original source files are also under the 3-clause BSD license, with
 337 the separate file `LICENSE`.