cmds/helptext: indent + newlines + synopsis
Juan Batiz-Benet committed
Nov 12, 2014 at 03:12 UTC
fc7c199d6ac55b7498a03ce6a793e2529679c378
2 files changed
+59
-15
commands/cli/helptext.go
+58
-15
@@ -29,10 +29,46 @@ type helpFields struct {
29
Tagline string
30
Arguments string
31
Options string
32
+ Synopsis string
33
Subcommands string
34
Description string
35
}
36
37
+// TrimNewlines removes extra newlines from fields. This makes aligning
38
+// commands easier. Below, the leading + tralining newlines are removed:
39
+// Synopsis: `
40
+// ipfs config <key> - Get value of <key>
41
+// ipfs config <key> <value> - Set value of <key> to <value>
42
+// ipfs config --show - Show config file
43
+// ipfs config --edit - Edit config file in $EDITOR
44
+// `
45
+func (f *helpFields) TrimNewlines() {
46
+ f.Path = strings.Trim(f.Path, "\n")
47
+ f.ArgUsage = strings.Trim(f.ArgUsage, "\n")
48
+ f.Tagline = strings.Trim(f.Tagline, "\n")
49
+ f.Arguments = strings.Trim(f.Arguments, "\n")
50
+ f.Options = strings.Trim(f.Options, "\n")
51
+ f.Synopsis = strings.Trim(f.Synopsis, "\n")
52
+ f.Subcommands = strings.Trim(f.Subcommands, "\n")
53
+ f.Description = strings.Trim(f.Description, "\n")
54
+}
55
+
56
+// Indent adds whitespace the lines of fields.
57
+func (f *helpFields) IndentAll() {
58
+ indent := func(s string) string {
59
+ if s == "" {
60
+ return s
61
+ }
62
+ return indentString(s, indentStr)
63
+ }
64
+
65
+ f.Arguments = indent(f.Arguments)
66
+ f.Options = indent(f.Options)
67
+ f.Synopsis = indent(f.Synopsis)
68
+ f.Subcommands = indent(f.Subcommands)
69
+ f.Description = indent(f.Description)
70
+}
71
+
72
const usageFormat = "{{if .Usage}}{{.Usage}}{{else}}{{.Path}}{{if .ArgUsage}} {{.ArgUsage}}{{end}} - {{.Tagline}}{{end}}"
73
74
const longHelpFormat = `
@@ -40,29 +76,31 @@ const longHelpFormat = `
76
77
{{if .Arguments}}ARGUMENTS:
78
43
-{{.Indent}}{{.Arguments}}
79
+{{.Arguments}}
80
81
{{end}}{{if .Options}}OPTIONS:
82
47
-{{.Indent}}{{.Options}}
83
+{{.Options}}
84
85
{{end}}{{if .Subcommands}}SUBCOMMANDS:
86
51
-{{.Indent}}{{.Subcommands}}
87
+{{.Subcommands}}
88
89
{{.Indent}}Use '{{.Path}} <subcmd> --help' for more information about each command.
90
91
{{end}}{{if .Description}}DESCRIPTION:
92
57
-{{.Indent}}{{.Description}}
93
+{{.Description}}
94
95
{{end}}
96
`
97
const shortHelpFormat = `USAGE:
98
99
{{.Indent}}{{template "usage" .}}
64
-{{if .Description}}
65
-{{.Indent}}{{.Description}}
100
+{{if .Synopsis}}
101
+{{.Synopsis}}
102
+{{end}}{{if .Description}}
103
+{{.Description}}
104
{{end}}
105
Use '{{.Path}} --help' for more information about this command.
106
`
@@ -111,6 +149,7 @@ func LongHelp(rootName string, root *cmds.Command, path []string, out io.Writer)
149
Tagline: cmd.Description,
150
Arguments: cmd.ArgumentHelp,
151
Options: cmd.OptionHelp,
152
+ Synopsis: cmd.Helptext.Synopsis,
153
Subcommands: cmd.SubcommandHelp,
154
Description: cmd.Help,
155
}
@@ -137,10 +176,11 @@ func LongHelp(rootName string, root *cmds.Command, path []string, out io.Writer)
176
fields.Subcommands = strings.Join(subcommandText(cmd, rootName, path), "\n")
177
}
178
140
- fields.Arguments = indentString(fields.Arguments, indentStr)
141
- fields.Options = indentString(fields.Options, indentStr)
142
- fields.Subcommands = indentString(fields.Subcommands, indentStr)
143
- fields.Description = indentString(fields.Description, indentStr)
179
+ // trim the extra newlines (see TrimNewlines doc)
180
+ fields.TrimNewlines()
181
+
182
+ // indent all fields that have been set
183
+ fields.IndentAll()
184
185
return longHelpTemplate.Execute(out, fields)
186
}
@@ -162,6 +202,7 @@ func ShortHelp(rootName string, root *cmds.Command, path []string, out io.Writer
202
Path: pathStr,
203
ArgUsage: usageText(cmd),
204
Tagline: cmd.Description,
205
+ Synopsis: cmd.Helptext.Synopsis,
206
Description: cmd.Help,
207
}
208
@@ -178,16 +219,18 @@ func ShortHelp(rootName string, root *cmds.Command, path []string, out io.Writer
219
if len(cmd.Helptext.Subcommands) > 0 {
220
fields.Subcommands = cmd.Helptext.Subcommands
221
}
181
- if len(cmd.Helptext.LongDescription) > 0 {
182
- fields.Description = cmd.Helptext.LongDescription
183
- } else if len(cmd.Helptext.ShortDescription) > 0 {
222
+ if len(cmd.Helptext.ShortDescription) > 0 {
223
fields.Description = cmd.Helptext.ShortDescription
224
}
225
if len(cmd.Helptext.Usage) > 0 {
226
fields.Usage = cmd.Helptext.Subcommands
227
}
228
190
- fields.Description = indentString(fields.Description, indentStr)
229
+ // trim the extra newlines (see TrimNewlines doc)
230
+ fields.TrimNewlines()
231
+
232
+ // indent all fields that have been set
233
+ fields.IndentAll()
234
235
return shortHelpTemplate.Execute(out, fields)
236
}
@@ -330,5 +373,5 @@ func indent(lines []string, prefix string) []string {
373
}
374
375
func indentString(line string, prefix string) string {
333
- return strings.Replace(line, "\n", "\n"+prefix, -1)
376
+ return prefix + strings.Replace(line, "\n", "\n"+prefix, -1)
377
}
commands/command.go
+1
@@ -25,6 +25,7 @@ type HelpText struct {
25
// required
26
Tagline string // used in <cmd usage>
27
ShortDescription string // used in DESCRIPTION
28
+ Synopsis string // showcasing the cmd
29
30
// optional - whole section overrides
31
Usage string // overrides USAGE section