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