1// Copyright 2014 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// Stringer is a tool to automate the creation of methods that satisfy the fmt.Stringer 6// interface. Given the name of a (signed or unsigned) integer type T that has constants 7// defined, stringer will create a new self-contained Go source file implementing 8// func (t T) String() string 9// The file is created in the same package and directory as the package that defines T. 10// It has helpful defaults designed for use with go generate. 11// 12// Stringer works best with constants that are consecutive values such as created using iota, 13// but creates good code regardless. In the future it might also provide custom support for 14// constant sets that are bit patterns. 15// 16// For example, given this snippet, 17// 18// package painkiller 19// 20// type Pill int 21// 22// const ( 23// Placebo Pill = iota 24// Aspirin 25// Ibuprofen 26// Paracetamol 27// Acetaminophen = Paracetamol 28// ) 29// 30// running this command 31// 32// stringer -type=Pill 33// 34// in the same directory will create the file pill_string.go, in package painkiller, 35// containing a definition of 36// 37// func (Pill) String() string 38// 39// That method will translate the value of a Pill constant to the string representation 40// of the respective constant name, so that the call fmt.Print(painkiller.Aspirin) will 41// print the string "Aspirin". 42// 43// Typically this process would be run using go generate, like this: 44// 45// //go:generate stringer -type=Pill 46// 47// If multiple constants have the same value, the lexically first matching name will 48// be used (in the example, Acetaminophen will print as "Paracetamol"). 49// 50// With no arguments, it processes the package in the current directory. 51// Otherwise, the arguments must name a single directory holding a Go package 52// or a set of Go source files that represent a single Go package. 53// 54// The -type flag accepts a comma-separated list of types so a single run can 55// generate methods for multiple types. The default output file is t_string.go, 56// where t is the lower-cased name of the first type listed. It can be overridden 57// with the -output flag. 58// 59package main // import "golang.org/x/tools/cmd/stringer" 60 61import ( 62 "bytes" 63 "flag" 64 "fmt" 65 "go/ast" 66 "go/constant" 67 "go/format" 68 "go/token" 69 "go/types" 70 "io/ioutil" 71 "log" 72 "os" 73 "path/filepath" 74 "sort" 75 "strings" 76 77 "golang.org/x/tools/go/packages" 78) 79 80var ( 81 typeNames = flag.String("type", "", "comma-separated list of type names; must be set") 82 output = flag.String("output", "", "output file name; default srcdir/<type>_string.go") 83 trimprefix = flag.String("trimprefix", "", "trim the `prefix` from the generated constant names") 84 linecomment = flag.Bool("linecomment", false, "use line comment text as printed text when present") 85 buildTags = flag.String("tags", "", "comma-separated list of build tags to apply") 86) 87 88// Usage is a replacement usage function for the flags package. 89func Usage() { 90 fmt.Fprintf(os.Stderr, "Usage of stringer:\n") 91 fmt.Fprintf(os.Stderr, "\tstringer [flags] -type T [directory]\n") 92 fmt.Fprintf(os.Stderr, "\tstringer [flags] -type T files... # Must be a single package\n") 93 fmt.Fprintf(os.Stderr, "For more information, see:\n") 94 fmt.Fprintf(os.Stderr, "\thttp://godoc.org/golang.org/x/tools/cmd/stringer\n") 95 fmt.Fprintf(os.Stderr, "Flags:\n") 96 flag.PrintDefaults() 97} 98 99func main() { 100 log.SetFlags(0) 101 log.SetPrefix("stringer: ") 102 flag.Usage = Usage 103 flag.Parse() 104 if len(*typeNames) == 0 { 105 flag.Usage() 106 os.Exit(2) 107 } 108 types := strings.Split(*typeNames, ",") 109 var tags []string 110 if len(*buildTags) > 0 { 111 tags = strings.Split(*buildTags, ",") 112 } 113 114 // We accept either one directory or a list of files. Which do we have? 115 args := flag.Args() 116 if len(args) == 0 { 117 // Default: process whole package in current directory. 118 args = []string{"."} 119 } 120 121 // Parse the package once. 122 var dir string 123 g := Generator{ 124 trimPrefix: *trimprefix, 125 lineComment: *linecomment, 126 } 127 // TODO(suzmue): accept other patterns for packages (directories, list of files, import paths, etc). 128 if len(args) == 1 && isDirectory(args[0]) { 129 dir = args[0] 130 } else { 131 if len(tags) != 0 { 132 log.Fatal("-tags option applies only to directories, not when files are specified") 133 } 134 dir = filepath.Dir(args[0]) 135 } 136 137 g.parsePackage(args, tags) 138 139 // Print the header and package clause. 140 g.Printf("// Code generated by \"stringer %s\"; DO NOT EDIT.\n", strings.Join(os.Args[1:], " ")) 141 g.Printf("\n") 142 g.Printf("package %s", g.pkg.name) 143 g.Printf("\n") 144 g.Printf("import \"strconv\"\n") // Used by all methods. 145 146 // Run generate for each type. 147 for _, typeName := range types { 148 g.generate(typeName) 149 } 150 151 // Format the output. 152 src := g.format() 153 154 // Write to file. 155 outputName := *output 156 if outputName == "" { 157 baseName := fmt.Sprintf("%s_string.go", types[0]) 158 outputName = filepath.Join(dir, strings.ToLower(baseName)) 159 } 160 err := ioutil.WriteFile(outputName, src, 0644) 161 if err != nil { 162 log.Fatalf("writing output: %s", err) 163 } 164} 165 166// isDirectory reports whether the named file is a directory. 167func isDirectory(name string) bool { 168 info, err := os.Stat(name) 169 if err != nil { 170 log.Fatal(err) 171 } 172 return info.IsDir() 173} 174 175// Generator holds the state of the analysis. Primarily used to buffer 176// the output for format.Source. 177type Generator struct { 178 buf bytes.Buffer // Accumulated output. 179 pkg *Package // Package we are scanning. 180 181 trimPrefix string 182 lineComment bool 183} 184 185func (g *Generator) Printf(format string, args ...interface{}) { 186 fmt.Fprintf(&g.buf, format, args...) 187} 188 189// File holds a single parsed file and associated data. 190type File struct { 191 pkg *Package // Package to which this file belongs. 192 file *ast.File // Parsed AST. 193 // These fields are reset for each type being generated. 194 typeName string // Name of the constant type. 195 values []Value // Accumulator for constant values of that type. 196 197 trimPrefix string 198 lineComment bool 199} 200 201type Package struct { 202 name string 203 defs map[*ast.Ident]types.Object 204 files []*File 205} 206 207// parsePackage analyzes the single package constructed from the patterns and tags. 208// parsePackage exits if there is an error. 209func (g *Generator) parsePackage(patterns []string, tags []string) { 210 cfg := &packages.Config{ 211 Mode: packages.LoadSyntax, 212 // TODO: Need to think about constants in test files. Maybe write type_string_test.go 213 // in a separate pass? For later. 214 Tests: false, 215 BuildFlags: []string{fmt.Sprintf("-tags=%s", strings.Join(tags, " "))}, 216 } 217 pkgs, err := packages.Load(cfg, patterns...) 218 if err != nil { 219 log.Fatal(err) 220 } 221 if len(pkgs) != 1 { 222 log.Fatalf("error: %d packages found", len(pkgs)) 223 } 224 g.addPackage(pkgs[0]) 225} 226 227// addPackage adds a type checked Package and its syntax files to the generator. 228func (g *Generator) addPackage(pkg *packages.Package) { 229 g.pkg = &Package{ 230 name: pkg.Name, 231 defs: pkg.TypesInfo.Defs, 232 files: make([]*File, len(pkg.Syntax)), 233 } 234 235 for i, file := range pkg.Syntax { 236 g.pkg.files[i] = &File{ 237 file: file, 238 pkg: g.pkg, 239 trimPrefix: g.trimPrefix, 240 lineComment: g.lineComment, 241 } 242 } 243} 244 245// generate produces the String method for the named type. 246func (g *Generator) generate(typeName string) { 247 values := make([]Value, 0, 100) 248 for _, file := range g.pkg.files { 249 // Set the state for this run of the walker. 250 file.typeName = typeName 251 file.values = nil 252 if file.file != nil { 253 ast.Inspect(file.file, file.genDecl) 254 values = append(values, file.values...) 255 } 256 } 257 258 if len(values) == 0 { 259 log.Fatalf("no values defined for type %s", typeName) 260 } 261 runs := splitIntoRuns(values) 262 // The decision of which pattern to use depends on the number of 263 // runs in the numbers. If there's only one, it's easy. For more than 264 // one, there's a tradeoff between complexity and size of the data 265 // and code vs. the simplicity of a map. A map takes more space, 266 // but so does the code. The decision here (crossover at 10) is 267 // arbitrary, but considers that for large numbers of runs the cost 268 // of the linear scan in the switch might become important, and 269 // rather than use yet another algorithm such as binary search, 270 // we punt and use a map. In any case, the likelihood of a map 271 // being necessary for any realistic example other than bitmasks 272 // is very low. And bitmasks probably deserve their own analysis, 273 // to be done some other day. 274 switch { 275 case len(runs) == 1: 276 g.buildOneRun(runs, typeName) 277 case len(runs) <= 10: 278 g.buildMultipleRuns(runs, typeName) 279 default: 280 g.buildMap(runs, typeName) 281 } 282} 283 284// splitIntoRuns breaks the values into runs of contiguous sequences. 285// For example, given 1,2,3,5,6,7 it returns {1,2,3},{5,6,7}. 286// The input slice is known to be non-empty. 287func splitIntoRuns(values []Value) [][]Value { 288 // We use stable sort so the lexically first name is chosen for equal elements. 289 sort.Stable(byValue(values)) 290 // Remove duplicates. Stable sort has put the one we want to print first, 291 // so use that one. The String method won't care about which named constant 292 // was the argument, so the first name for the given value is the only one to keep. 293 // We need to do this because identical values would cause the switch or map 294 // to fail to compile. 295 j := 1 296 for i := 1; i < len(values); i++ { 297 if values[i].value != values[i-1].value { 298 values[j] = values[i] 299 j++ 300 } 301 } 302 values = values[:j] 303 runs := make([][]Value, 0, 10) 304 for len(values) > 0 { 305 // One contiguous sequence per outer loop. 306 i := 1 307 for i < len(values) && values[i].value == values[i-1].value+1 { 308 i++ 309 } 310 runs = append(runs, values[:i]) 311 values = values[i:] 312 } 313 return runs 314} 315 316// format returns the gofmt-ed contents of the Generator's buffer. 317func (g *Generator) format() []byte { 318 src, err := format.Source(g.buf.Bytes()) 319 if err != nil { 320 // Should never happen, but can arise when developing this code. 321 // The user can compile the output to see the error. 322 log.Printf("warning: internal error: invalid Go generated: %s", err) 323 log.Printf("warning: compile the package to analyze the error") 324 return g.buf.Bytes() 325 } 326 return src 327} 328 329// Value represents a declared constant. 330type Value struct { 331 name string // The name of the constant. 332 // The value is stored as a bit pattern alone. The boolean tells us 333 // whether to interpret it as an int64 or a uint64; the only place 334 // this matters is when sorting. 335 // Much of the time the str field is all we need; it is printed 336 // by Value.String. 337 value uint64 // Will be converted to int64 when needed. 338 signed bool // Whether the constant is a signed type. 339 str string // The string representation given by the "go/constant" package. 340} 341 342func (v *Value) String() string { 343 return v.str 344} 345 346// byValue lets us sort the constants into increasing order. 347// We take care in the Less method to sort in signed or unsigned order, 348// as appropriate. 349type byValue []Value 350 351func (b byValue) Len() int { return len(b) } 352func (b byValue) Swap(i, j int) { b[i], b[j] = b[j], b[i] } 353func (b byValue) Less(i, j int) bool { 354 if b[i].signed { 355 return int64(b[i].value) < int64(b[j].value) 356 } 357 return b[i].value < b[j].value 358} 359 360// genDecl processes one declaration clause. 361func (f *File) genDecl(node ast.Node) bool { 362 decl, ok := node.(*ast.GenDecl) 363 if !ok || decl.Tok != token.CONST { 364 // We only care about const declarations. 365 return true 366 } 367 // The name of the type of the constants we are declaring. 368 // Can change if this is a multi-element declaration. 369 typ := "" 370 // Loop over the elements of the declaration. Each element is a ValueSpec: 371 // a list of names possibly followed by a type, possibly followed by values. 372 // If the type and value are both missing, we carry down the type (and value, 373 // but the "go/types" package takes care of that). 374 for _, spec := range decl.Specs { 375 vspec := spec.(*ast.ValueSpec) // Guaranteed to succeed as this is CONST. 376 if vspec.Type == nil && len(vspec.Values) > 0 { 377 // "X = 1". With no type but a value. If the constant is untyped, 378 // skip this vspec and reset the remembered type. 379 typ = "" 380 381 // If this is a simple type conversion, remember the type. 382 // We don't mind if this is actually a call; a qualified call won't 383 // be matched (that will be SelectorExpr, not Ident), and only unusual 384 // situations will result in a function call that appears to be 385 // a type conversion. 386 ce, ok := vspec.Values[0].(*ast.CallExpr) 387 if !ok { 388 continue 389 } 390 id, ok := ce.Fun.(*ast.Ident) 391 if !ok { 392 continue 393 } 394 typ = id.Name 395 } 396 if vspec.Type != nil { 397 // "X T". We have a type. Remember it. 398 ident, ok := vspec.Type.(*ast.Ident) 399 if !ok { 400 continue 401 } 402 typ = ident.Name 403 } 404 if typ != f.typeName { 405 // This is not the type we're looking for. 406 continue 407 } 408 // We now have a list of names (from one line of source code) all being 409 // declared with the desired type. 410 // Grab their names and actual values and store them in f.values. 411 for _, name := range vspec.Names { 412 if name.Name == "_" { 413 continue 414 } 415 // This dance lets the type checker find the values for us. It's a 416 // bit tricky: look up the object declared by the name, find its 417 // types.Const, and extract its value. 418 obj, ok := f.pkg.defs[name] 419 if !ok { 420 log.Fatalf("no value for constant %s", name) 421 } 422 info := obj.Type().Underlying().(*types.Basic).Info() 423 if info&types.IsInteger == 0 { 424 log.Fatalf("can't handle non-integer constant type %s", typ) 425 } 426 value := obj.(*types.Const).Val() // Guaranteed to succeed as this is CONST. 427 if value.Kind() != constant.Int { 428 log.Fatalf("can't happen: constant is not an integer %s", name) 429 } 430 i64, isInt := constant.Int64Val(value) 431 u64, isUint := constant.Uint64Val(value) 432 if !isInt && !isUint { 433 log.Fatalf("internal error: value of %s is not an integer: %s", name, value.String()) 434 } 435 if !isInt { 436 u64 = uint64(i64) 437 } 438 v := Value{ 439 name: name.Name, 440 value: u64, 441 signed: info&types.IsUnsigned == 0, 442 str: value.String(), 443 } 444 if c := vspec.Comment; f.lineComment && c != nil && len(c.List) == 1 { 445 v.name = strings.TrimSpace(c.Text()) 446 } 447 v.name = strings.TrimPrefix(v.name, f.trimPrefix) 448 f.values = append(f.values, v) 449 } 450 } 451 return false 452} 453 454// Helpers 455 456// usize returns the number of bits of the smallest unsigned integer 457// type that will hold n. Used to create the smallest possible slice of 458// integers to use as indexes into the concatenated strings. 459func usize(n int) int { 460 switch { 461 case n < 1<<8: 462 return 8 463 case n < 1<<16: 464 return 16 465 default: 466 // 2^32 is enough constants for anyone. 467 return 32 468 } 469} 470 471// declareIndexAndNameVars declares the index slices and concatenated names 472// strings representing the runs of values. 473func (g *Generator) declareIndexAndNameVars(runs [][]Value, typeName string) { 474 var indexes, names []string 475 for i, run := range runs { 476 index, name := g.createIndexAndNameDecl(run, typeName, fmt.Sprintf("_%d", i)) 477 if len(run) != 1 { 478 indexes = append(indexes, index) 479 } 480 names = append(names, name) 481 } 482 g.Printf("const (\n") 483 for _, name := range names { 484 g.Printf("\t%s\n", name) 485 } 486 g.Printf(")\n\n") 487 488 if len(indexes) > 0 { 489 g.Printf("var (") 490 for _, index := range indexes { 491 g.Printf("\t%s\n", index) 492 } 493 g.Printf(")\n\n") 494 } 495} 496 497// declareIndexAndNameVar is the single-run version of declareIndexAndNameVars 498func (g *Generator) declareIndexAndNameVar(run []Value, typeName string) { 499 index, name := g.createIndexAndNameDecl(run, typeName, "") 500 g.Printf("const %s\n", name) 501 g.Printf("var %s\n", index) 502} 503 504// createIndexAndNameDecl returns the pair of declarations for the run. The caller will add "const" and "var". 505func (g *Generator) createIndexAndNameDecl(run []Value, typeName string, suffix string) (string, string) { 506 b := new(bytes.Buffer) 507 indexes := make([]int, len(run)) 508 for i := range run { 509 b.WriteString(run[i].name) 510 indexes[i] = b.Len() 511 } 512 nameConst := fmt.Sprintf("_%s_name%s = %q", typeName, suffix, b.String()) 513 nameLen := b.Len() 514 b.Reset() 515 fmt.Fprintf(b, "_%s_index%s = [...]uint%d{0, ", typeName, suffix, usize(nameLen)) 516 for i, v := range indexes { 517 if i > 0 { 518 fmt.Fprintf(b, ", ") 519 } 520 fmt.Fprintf(b, "%d", v) 521 } 522 fmt.Fprintf(b, "}") 523 return b.String(), nameConst 524} 525 526// declareNameVars declares the concatenated names string representing all the values in the runs. 527func (g *Generator) declareNameVars(runs [][]Value, typeName string, suffix string) { 528 g.Printf("const _%s_name%s = \"", typeName, suffix) 529 for _, run := range runs { 530 for i := range run { 531 g.Printf("%s", run[i].name) 532 } 533 } 534 g.Printf("\"\n") 535} 536 537// buildOneRun generates the variables and String method for a single run of contiguous values. 538func (g *Generator) buildOneRun(runs [][]Value, typeName string) { 539 values := runs[0] 540 g.Printf("\n") 541 g.declareIndexAndNameVar(values, typeName) 542 // The generated code is simple enough to write as a Printf format. 543 lessThanZero := "" 544 if values[0].signed { 545 lessThanZero = "i < 0 || " 546 } 547 if values[0].value == 0 { // Signed or unsigned, 0 is still 0. 548 g.Printf(stringOneRun, typeName, usize(len(values)), lessThanZero) 549 } else { 550 g.Printf(stringOneRunWithOffset, typeName, values[0].String(), usize(len(values)), lessThanZero) 551 } 552} 553 554// Arguments to format are: 555// [1]: type name 556// [2]: size of index element (8 for uint8 etc.) 557// [3]: less than zero check (for signed types) 558const stringOneRun = `func (i %[1]s) String() string { 559 if %[3]si >= %[1]s(len(_%[1]s_index)-1) { 560 return "%[1]s(" + strconv.FormatInt(int64(i), 10) + ")" 561 } 562 return _%[1]s_name[_%[1]s_index[i]:_%[1]s_index[i+1]] 563} 564` 565 566// Arguments to format are: 567// [1]: type name 568// [2]: lowest defined value for type, as a string 569// [3]: size of index element (8 for uint8 etc.) 570// [4]: less than zero check (for signed types) 571/* 572 */ 573const stringOneRunWithOffset = `func (i %[1]s) String() string { 574 i -= %[2]s 575 if %[4]si >= %[1]s(len(_%[1]s_index)-1) { 576 return "%[1]s(" + strconv.FormatInt(int64(i + %[2]s), 10) + ")" 577 } 578 return _%[1]s_name[_%[1]s_index[i] : _%[1]s_index[i+1]] 579} 580` 581 582// buildMultipleRuns generates the variables and String method for multiple runs of contiguous values. 583// For this pattern, a single Printf format won't do. 584func (g *Generator) buildMultipleRuns(runs [][]Value, typeName string) { 585 g.Printf("\n") 586 g.declareIndexAndNameVars(runs, typeName) 587 g.Printf("func (i %s) String() string {\n", typeName) 588 g.Printf("\tswitch {\n") 589 for i, values := range runs { 590 if len(values) == 1 { 591 g.Printf("\tcase i == %s:\n", &values[0]) 592 g.Printf("\t\treturn _%s_name_%d\n", typeName, i) 593 continue 594 } 595 g.Printf("\tcase %s <= i && i <= %s:\n", &values[0], &values[len(values)-1]) 596 if values[0].value != 0 { 597 g.Printf("\t\ti -= %s\n", &values[0]) 598 } 599 g.Printf("\t\treturn _%s_name_%d[_%s_index_%d[i]:_%s_index_%d[i+1]]\n", 600 typeName, i, typeName, i, typeName, i) 601 } 602 g.Printf("\tdefault:\n") 603 g.Printf("\t\treturn \"%s(\" + strconv.FormatInt(int64(i), 10) + \")\"\n", typeName) 604 g.Printf("\t}\n") 605 g.Printf("}\n") 606} 607 608// buildMap handles the case where the space is so sparse a map is a reasonable fallback. 609// It's a rare situation but has simple code. 610func (g *Generator) buildMap(runs [][]Value, typeName string) { 611 g.Printf("\n") 612 g.declareNameVars(runs, typeName, "") 613 g.Printf("\nvar _%s_map = map[%s]string{\n", typeName, typeName) 614 n := 0 615 for _, values := range runs { 616 for _, value := range values { 617 g.Printf("\t%s: _%s_name[%d:%d],\n", &value, typeName, n, n+len(value.name)) 618 n += len(value.name) 619 } 620 } 621 g.Printf("}\n\n") 622 g.Printf(stringMap, typeName) 623} 624 625// Argument to format is the type name. 626const stringMap = `func (i %[1]s) String() string { 627 if str, ok := _%[1]s_map[i]; ok { 628 return str 629 } 630 return "%[1]s(" + strconv.FormatInt(int64(i), 10) + ")" 631} 632` 633