libgo/go/cmd/go/internal/help/help.go

   1 // Copyright 2017 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 // Package help implements the ``go help'' command.
   6 package help
   7
   8 import (
   9         "bufio"
  10         "bytes"
  11         "fmt"
  12         "io"
  13         "os"
  14         "strings"
  15         "text/template"
  16         "unicode"
  17         "unicode/utf8"
  18
  19         "cmd/go/internal/base"
  20         "cmd/go/internal/modload"
  21 )
  22
  23 // Help implements the 'help' command.
  24 func Help(w io.Writer, args []string) {
  25         // 'go help documentation' generates doc.go.
  26         if len(args) == 1 && args[0] == "documentation" {
  27                 fmt.Fprintln(w, "// Copyright 2011 The Go Authors. All rights reserved.")
  28                 fmt.Fprintln(w, "// Use of this source code is governed by a BSD-style")
  29                 fmt.Fprintln(w, "// license that can be found in the LICENSE file.")
  30                 fmt.Fprintln(w)
  31                 fmt.Fprintln(w, "// Code generated by mkalldocs.sh; DO NOT EDIT.")
  32                 fmt.Fprintln(w, "// Edit the documentation in other files and rerun mkalldocs.sh to generate this one.")
  33                 fmt.Fprintln(w)
  34                 buf := new(bytes.Buffer)
  35                 PrintUsage(buf, base.Go)
  36                 usage := &base.Command{Long: buf.String()}
  37                 cmds := []*base.Command{usage}
  38                 for _, cmd := range base.Go.Commands {
  39                         // Avoid duplication of the "get" documentation.
  40                         if cmd.UsageLine == "module-get" && modload.Enabled() {
  41                                 continue
  42                         } else if cmd.UsageLine == "gopath-get" && !modload.Enabled() {
  43                                 continue
  44                         }
  45                         cmds = append(cmds, cmd)
  46                         cmds = append(cmds, cmd.Commands...)
  47                 }
  48                 tmpl(&commentWriter{W: w}, documentationTemplate, cmds)
  49                 fmt.Fprintln(w, "package main")
  50                 return
  51         }
  52
  53         cmd := base.Go
  54 Args:
  55         for i, arg := range args {
  56                 for _, sub := range cmd.Commands {
  57                         if sub.Name() == arg {
  58                                 cmd = sub
  59                                 continue Args
  60                         }
  61                 }
  62
  63                 // helpSuccess is the help command using as many args as possible that would succeed.
  64                 helpSuccess := "go help"
  65                 if i > 0 {
  66                         helpSuccess += " " + strings.Join(args[:i], " ")
  67                 }
  68                 fmt.Fprintf(os.Stderr, "go help %s: unknown help topic. Run '%s'.\n", strings.Join(args, " "), helpSuccess)
  69                 base.SetExitStatus(2) // failed at 'go help cmd'
  70                 base.Exit()
  71         }
  72
  73         if len(cmd.Commands) > 0 {
  74                 PrintUsage(os.Stdout, cmd)
  75         } else {
  76                 tmpl(os.Stdout, helpTemplate, cmd)
  77         }
  78         // not exit 2: succeeded at 'go help cmd'.
  79         return
  80 }
  81
  82 var usageTemplate = `{{.Long | trim}}
  83
  84 Usage:
  85
  86         {{.UsageLine}} <command> [arguments]
  87
  88 The commands are:
  89 {{range .Commands}}{{if or (.Runnable) .Commands}}
  90         {{.Name | printf "%-11s"}} {{.Short}}{{end}}{{end}}
  91
  92 Use "go help{{with .LongName}} {{.}}{{end}} <command>" for more information about a command.
  93 {{if eq (.UsageLine) "go"}}
  94 Additional help topics:
  95 {{range .Commands}}{{if and (not .Runnable) (not .Commands)}}
  96         {{.Name | printf "%-15s"}} {{.Short}}{{end}}{{end}}
  97
  98 Use "go help{{with .LongName}} {{.}}{{end}} <topic>" for more information about that topic.
  99 {{end}}
 100 `
 101
 102 var helpTemplate = `{{if .Runnable}}usage: {{.UsageLine}}
 103
 104 {{end}}{{.Long | trim}}
 105 `
 106
 107 var documentationTemplate = `{{range .}}{{if .Short}}{{.Short | capitalize}}
 108
 109 {{end}}{{if .Commands}}` + usageTemplate + `{{else}}{{if .Runnable}}Usage:
 110
 111         {{.UsageLine}}
 112
 113 {{end}}{{.Long | trim}}
 114
 115
 116 {{end}}{{end}}`
 117
 118 // commentWriter writes a Go comment to the underlying io.Writer,
 119 // using line comment form (//).
 120 type commentWriter struct {
 121         W            io.Writer
 122         wroteSlashes bool // Wrote "//" at the beginning of the current line.
 123 }
 124
 125 func (c *commentWriter) Write(p []byte) (int, error) {
 126         var n int
 127         for i, b := range p {
 128                 if !c.wroteSlashes {
 129                         s := "//"
 130                         if b != '\n' {
 131                                 s = "// "
 132                         }
 133                         if _, err := io.WriteString(c.W, s); err != nil {
 134                                 return n, err
 135                         }
 136                         c.wroteSlashes = true
 137                 }
 138                 n0, err := c.W.Write(p[i : i+1])
 139                 n += n0
 140                 if err != nil {
 141                         return n, err
 142                 }
 143                 if b == '\n' {
 144                         c.wroteSlashes = false
 145                 }
 146         }
 147         return len(p), nil
 148 }
 149
 150 // An errWriter wraps a writer, recording whether a write error occurred.
 151 type errWriter struct {
 152         w   io.Writer
 153         err error
 154 }
 155
 156 func (w *errWriter) Write(b []byte) (int, error) {
 157         n, err := w.w.Write(b)
 158         if err != nil {
 159                 w.err = err
 160         }
 161         return n, err
 162 }
 163
 164 // tmpl executes the given template text on data, writing the result to w.
 165 func tmpl(w io.Writer, text string, data any) {
 166         t := template.New("top")
 167         t.Funcs(template.FuncMap{"trim": strings.TrimSpace, "capitalize": capitalize})
 168         template.Must(t.Parse(text))
 169         ew := &errWriter{w: w}
 170         err := t.Execute(ew, data)
 171         if ew.err != nil {
 172                 // I/O error writing. Ignore write on closed pipe.
 173                 if strings.Contains(ew.err.Error(), "pipe") {
 174                         base.SetExitStatus(1)
 175                         base.Exit()
 176                 }
 177                 base.Fatalf("writing output: %v", ew.err)
 178         }
 179         if err != nil {
 180                 panic(err)
 181         }
 182 }
 183
 184 func capitalize(s string) string {
 185         if s == "" {
 186                 return s
 187         }
 188         r, n := utf8.DecodeRuneInString(s)
 189         return string(unicode.ToTitle(r)) + s[n:]
 190 }
 191
 192 func PrintUsage(w io.Writer, cmd *base.Command) {
 193         bw := bufio.NewWriter(w)
 194         tmpl(bw, usageTemplate, cmd)
 195         bw.Flush()
 196 }