github.com/FenixAra/go@v0.0.0-20170127160404-96ea0918e670/src/cmd/gofmt/doc.go (about)

     1  // Copyright 2009 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  Gofmt formats Go programs.
     7  It uses tabs (width = 8) for indentation and blanks for alignment.
     8  
     9  Without an explicit path, it processes the standard input.  Given a file,
    10  it operates on that file; given a directory, it operates on all .go files in
    11  that directory, recursively.  (Files starting with a period are ignored.)
    12  By default, gofmt prints the reformatted sources to standard output.
    13  
    14  Usage:
    15  	gofmt [flags] [path ...]
    16  
    17  The flags are:
    18  	-d
    19  		Do not print reformatted sources to standard output.
    20  		If a file's formatting is different than gofmt's, print diffs
    21  		to standard output.
    22  	-e
    23  		Print all (including spurious) errors.
    24  	-l
    25  		Do not print reformatted sources to standard output.
    26  		If a file's formatting is different from gofmt's, print its name
    27  		to standard output.
    28  	-r rule
    29  		Apply the rewrite rule to the source before reformatting.
    30  	-s
    31  		Try to simplify code (after applying the rewrite rule, if any).
    32  	-w
    33  		Do not print reformatted sources to standard output.
    34  		If a file's formatting is different from gofmt's, overwrite it
    35  		with gofmt's version. If an error occurred during overwriting,
    36  		the original file is restored from an automatic backup.
    37  
    38  Debugging support:
    39  	-cpuprofile filename
    40  		Write cpu profile to the specified file.
    41  
    42  
    43  The rewrite rule specified with the -r flag must be a string of the form:
    44  
    45  	pattern -> replacement
    46  
    47  Both pattern and replacement must be valid Go expressions.
    48  In the pattern, single-character lowercase identifiers serve as
    49  wildcards matching arbitrary sub-expressions; those expressions
    50  will be substituted for the same identifiers in the replacement.
    51  
    52  When gofmt reads from standard input, it accepts either a full Go program
    53  or a program fragment.  A program fragment must be a syntactically
    54  valid declaration list, statement list, or expression.  When formatting
    55  such a fragment, gofmt preserves leading indentation as well as leading
    56  and trailing spaces, so that individual sections of a Go program can be
    57  formatted by piping them through gofmt.
    58  
    59  Examples
    60  
    61  To check files for unnecessary parentheses:
    62  
    63  	gofmt -r '(a) -> a' -l *.go
    64  
    65  To remove the parentheses:
    66  
    67  	gofmt -r '(a) -> a' -w *.go
    68  
    69  To convert the package tree from explicit slice upper bounds to implicit ones:
    70  
    71  	gofmt -r 'α[β:len(α)] -> α[β:]' -w $GOROOT/src
    72  
    73  The simplify command
    74  
    75  When invoked with -s gofmt will make the following source transformations where possible.
    76  
    77  	An array, slice, or map composite literal of the form:
    78  		[]T{T{}, T{}}
    79  	will be simplified to:
    80  		[]T{{}, {}}
    81  
    82  	A slice expression of the form:
    83  		s[a:len(s)]
    84  	will be simplified to:
    85  		s[a:]
    86  
    87  	A range of the form:
    88  		for x, _ = range v {...}
    89  	will be simplified to:
    90  		for x = range v {...}
    91  
    92  	A range of the form:
    93  		for _ = range v {...}
    94  	will be simplified to:
    95  		for range v {...}
    96  
    97  This may result in changes that are incompatible with earlier versions of Go.
    98  */
    99  package main
   100  
   101  // BUG(rsc): The implementation of -r is a bit slow.
   102  // BUG(gri): If -w fails, the restored original file may not have some of the
   103  //           original file attributes.