Skip to content

G
go
Commit 36b32911 authored by Robert Griesemer's avatar Robert Griesemer
Browse files
Options

cmd/compile: update fmt.go internal documentation 

No code changes.

Change-Id: I7a22b3fbd6d727b276c7559f064cb0fdf385c02b
Reviewed-on: https://go-review.googlesource.com/28955Reviewed-by: default avatarMatthew Dempsky <mdempsky@google.com>
parent 6537e18f
Hide whitespace changes
Inline Side-by-side
Showing with 63 additions and 76 deletions
src/cmd/compile/internal/gc/fmt.go
View file @ 36b32911
......@@ -12,24 +12,24 @@ import (
"unicode/utf8"
)
// TODO(gri) update documentation thoroughly
// A FmtFlag value is a set of flags (or 0).
// They control how the Xconv functions format their values.
// See the respective function's documentation for details.
type FmtFlag int
const ( // fmt.Format flag/prec or verb
FmtLeft FmtFlag = 1 << iota // "-" => '-'
FmtSharp // "#" => '#'
FmtSign // "+" => '+'
FmtUnsigned // "u" => ' '
FmtShort // "h" => verb == 'S' (Short)
FmtLong // "l" => verb == 'L' (Long)
FmtComma // "," => '.' (== hasPrec)
FmtByte // "hh" => '0'
const ( // fmt.Format flag/prec or verb
FmtLeft FmtFlag = 1 << iota // '-'
FmtSharp // '#'
FmtSign // '+'
FmtUnsigned // ' ' (historic: u flag)
FmtShort // verb == 'S' (historic: h flag)
FmtLong // verb == 'L' (historic: l flag)
FmtComma // '.' (== hasPrec) (historic: , flag)
FmtByte // '0' (historic: hh flag)
)
// fmtFlag computes the (internal) FmtFlag
// value given the fmt.State and format verb.
func fmtFlag(s fmt.State, verb rune) FmtFlag {
var flag FmtFlag
if s.Flag('-') {
......@@ -59,45 +59,38 @@ func fmtFlag(s fmt.State, verb rune) FmtFlag {
return flag
}
// Format conversions:
// TODO(gri) verify these; eliminate those not used anymore
//
// Format conversions
// %L int Line numbers
//
// %E int etype values (aka 'Kind')
//
// %O int Node Opcodes
// Flags: "%#O": print go syntax. (automatic unless fmtmode == FDbg)
//
// %J Node* Node details
// Flags: "%hJ" suppresses things not relevant until walk.
//
// %V Val* Constant values
// %v Op Node opcodes
// Flags: #: print Go syntax (automatic unless fmtmode == FDbg)
//
// %S Sym* Symbols
// Flags: +,- #: mode (see below)
// "%hS" unqualified identifier in any mode
// "%hhS" in export mode: unqualified identifier if exported, qualified if not
// %j *Node Node details
// Flags: 0: suppresses things not relevant until walk
//
// %T Type* Types
// Flags: +,- #: mode (see below)
// 'l' definition instead of name.
// 'h' omit "func" and receiver in function types
// 'u' (only in -/Sym mode) print type identifiers wit package name instead of prefix.
// %v *Val Constant values
//
// %N Node* Nodes
// Flags: +,- #: mode (see below)
// 'h' (only in +/debug mode) suppress recursion
// 'l' (only in Error mode) print "foo (type Bar)"
// %v *Sym Symbols
// %S unqualified identifier in any mode
// Flags: +,- #: mode (see below)
// 0: in export mode: unqualified identifier if exported, qualified if not
//
// %H Nodes Nodes
// Flags: those of %N
// ',' separate items with ',' instead of ';'
// %v *Type Types
// %S omit "func" and receiver in function types
// %L definition instead of name.
// Flags: +,- #: mode (see below)
// ' ' (only in -/Sym mode) print type identifiers wit package name instead of prefix.
//
// In mparith2.go and mparith3.go:
// %B Mpint* Big integers
// %F Mpflt* Big floats
// %v *Node Nodes
// %S (only in +/debug mode) suppress recursion
// %L (only in Error mode) print "foo (type Bar)"
// Flags: +,- #: mode (see below)
//
// %S, %T and %N obey use the following flags to set the format mode:
// %v Nodes Node lists
// Flags: those of *Node
// .: separate items with ',' instead of ';'
// *Sym, *Type, and *Node types use the flags below to set the format mode
const (
FErr = iota
FDbg
......@@ -106,31 +99,33 @@ const (
var fmtmode int = FErr
var fmtpkgpfx int // %uT stickyness
var fmtpkgpfx int // "% v" stickyness for *Type objects
// The mode flags '+', '-', and '#' are sticky; they persist through
// recursions of *Node, *Type, and *Sym values. The ' ' flag is
// sticky only on *Type recursions and only used in %-/*Sym mode.
//
// E.g. for %S: %+S %#S %-S print an identifier properly qualified for debug/export/internal mode.
//
// The mode flags +, - and # are sticky, meaning they persist through
// recursions of %N, %T and %S, but not the h and l flags. The u flag is
// sticky only on %T recursions and only used in %-/Sym mode.
// Example: given a *Sym: %+v %#v %-v print an identifier properly qualified for debug/export/internal mode
//
// Useful format combinations:
// TODO(gri): verify these
//
// %+N %+H multiline recursive debug dump of node/nodelist
// %+hN %+hH non recursive debug dump
// *Node, Nodes:
// %+v multiline recursive debug dump of *Node/Nodes
// %+S non-recursive debug dump
//
// %#N %#T export format
// %#lT type definition instead of name
// %#hT omit"func" and receiver in function signature
// *Node:
// %#v Go format
// %L "foo (type Bar)" for error messages
//
// %lN "foo (type Bar)" for error messages
//
// %-T type identifiers
// %-hT type identifiers without "func" and arg names in type signatures (methodsym)
// %-uT type identifiers with package name instead of prefix (typesym, dcommontype, typehash)
// *Type:
// %#v Go format
// %#L type definition instead of name
// %#S omit"func" and receiver in function signature
//
// %-v type identifiers
// %-S type identifiers without "func" and arg names in type signatures (methodsym)
// %- v type identifiers with package name instead of prefix (typesym, dcommontype, typehash)
func setfmode(flags *FmtFlag) (fm int) {
fm = fmtmode
......@@ -146,8 +141,6 @@ func setfmode(flags *FmtFlag) (fm int) {
return
}
// Fmt "%L": Linenumbers
var goopnames = []string{
OADDR: "&",
OADD: "+",
......@@ -269,7 +262,7 @@ func (n *Node) Format(s fmt.State, verb rune) {
}
}
// Node details
// *Node details
func (n *Node) jconv(s fmt.State, flag FmtFlag) {
c := flag & FmtShort
......@@ -387,7 +380,6 @@ func (v Val) Format(s fmt.State, verb rune) {
}
}
// Fmt "%V": Values
func (v Val) vconv(s fmt.State, flag FmtFlag) {
switch u := v.U.(type) {
case *Mpint:
......@@ -514,7 +506,6 @@ func (et EType) String() string {
return fmt.Sprintf("E-%d", et)
}
// Fmt "%S": syms
func (s *Sym) symfmt(f fmt.State, flag FmtFlag) {
if s.Pkg != nil && flag&FmtShort == 0 {
switch fmtmode {
......@@ -1593,8 +1584,7 @@ func (s *Sym) String() string {
return fmt.Sprint(s)
}
// Fmt "%S": syms
// Flags: "%hS" suppresses qualifying with package
// "%S" suppresses qualifying with package
func (s *Sym) sconv(f fmt.State, flag FmtFlag) {
if flag&FmtLong != 0 {
panic("linksymfmt")
......@@ -1706,10 +1696,9 @@ func (t *Type) Format(s fmt.State, verb rune) {
}
}
// Fmt "%T": types.
// Flags: 'l' print definition, not name
// 'h' omit 'func' and receiver from function types, short type names
// 'u' package name, not prefix (FTypeId mode, sticky)
// "%L" print definition, not name
// "%S" omit 'func' and receiver from function types, short type names
// "% v" package name, not prefix (FTypeId mode, sticky)
func (t *Type) tconv(s fmt.State, flag FmtFlag) {
if t == nil {
fmt.Fprint(s, "<T>")
......@@ -1747,9 +1736,8 @@ func (n *Node) String() string {
return fmt.Sprint(n)
}
// Fmt '%N': Nodes.
// Flags: 'l' suffix with "(type %T)" where possible
// '+h' in debug mode, don't recurse, no multiline output
// "%L" suffix with "(type %T)" where possible
// "%+S" in debug mode, don't recurse, no multiline output
func (n *Node) Nconv(s fmt.State, flag FmtFlag) {
if n == nil {
fmt.Fprint(s, "<N>")
......@@ -1790,8 +1778,7 @@ func (n Nodes) String() string {
return fmt.Sprint(n)
}
// Fmt '%H': Nodes.
// Flags: all those of %N plus ',': separate with comma's instead of semicolons.
// Flags: all those of %N plus '.': separate with comma's instead of semicolons.
func (l Nodes) hconv(s fmt.State, flag FmtFlag) {
if l.Len() == 0 && fmtmode == FDbg {
fmt.Fprint(s, "<nil>")
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7