Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fmt: more doc needed for Formatter #42476

Open
dolmen opened this issue Nov 10, 2020 · 5 comments
Open

fmt: more doc needed for Formatter #42476

dolmen opened this issue Nov 10, 2020 · 5 comments
Labels
Documentation Issues describing a change to documentation. help wanted NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone

Comments

@dolmen
Copy link
Contributor

dolmen commented Nov 10, 2020

Current (go1.15, tip) documentation of interface fmt.Formatter:

Formatter is implemented by any value that has a Format method. The implementation controls how State and rune are interpreted, and may call Sprint(f) or Fprint(f) etc. to generate its output.

This is insufficient to tell how one must implement this interface:

  • which verbs should be handled for each type?
  • how to handle unhandled verbs?
  • how to forward unhandled verbs to Printf?
  • how to handle unhandled width?
  • how to handle unhandled precision?
  • lack of example
@martisch
Copy link
Contributor

There are no constraints how to implement formatters apart from the function signature. Its up to the developer to decide what should be handled how for each type. Which verbs produce output and which dont. Which verbs are implemented directly and which are formatted using other functions.

An example could be added. Contributions welcome.

@martisch martisch added Documentation Issues describing a change to documentation. help wanted labels Nov 10, 2020
@cagedmantis cagedmantis added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Nov 10, 2020
@cagedmantis cagedmantis added this to the Backlog milestone Nov 10, 2020
@dolmen
Copy link
Contributor Author

dolmen commented Nov 12, 2020

Yes, there are no constraints. But guidelines or best practices would still be helpful.

Also the stdlib has very few implementation of that interface (grep 'Format(fmt\.State,' $(go env GOROOT)/api/*.txt lists only 2 in package math/big) so reference code is limited.

@Windsooon
Copy link

It will be great to add an example for it. I would love to create a PR if needed.

@Windsooon
Copy link

Windsooon commented Sep 1, 2021

To maintain consistency, I used GoStringer's example. Maybe we can add more verbs in the example if needed.

package main

import (
	"fmt"
)

// Address has a City, State and a Country.
type Address struct {
	City    string
	State   string
	Country string
}

// Person has a Name, Age and Address.
type Person struct {
	Name string
	Age  uint
	Addr *Address
}

// Format makes Person satisfy the Formatter interface.
func (p Person) Format(state fmt.State, verb rune) {
	switch verb {
	case 'v':
		fmt.Fprint(state, "{Name: \""+p.Name+"\", ")
		fmt.Fprint(state, "Age: "+fmt.Sprint(p.Age))
		fmt.Fprint(state, "}")
	}
}

func main() {
	p1 := Person{
		Name: "Warren",
		Age:  31,
		Addr: &Address{
			City:    "Denver",
			State:   "CO",
			Country: "U.S.A.",
		},
	}
	// If Format() wasn't implemented, the output of `fmt.Printf("%s\n", p1)` would be similar to
	// {Warren 31 0xc0000121b0}
	fmt.Printf("%v\n", p1)

	p2 := Person{
		Name: "Theia",
		Age:  4,
	}
	// If Format() wasn't implemented, the output of `fmt.Printf("%s\n", p2)` would be similar to
	// {Theia 4 <nil>}
	fmt.Printf("%v\n", p2)
}

Thanks to https://blog.gopheracademy.com/advent-2018/fmt/

@dolmen
Copy link
Contributor Author

dolmen commented Apr 1, 2022

Your example shows an implementation of Format that implemts %v, but has no specific implementation for %#v, %+v or even %s which now do nothing instead of having the default behaviour for a struct type.

My point of view would be that it is an incomplete implementation of Format but, as there is no guidance on what would be a correct implementation, I'm not sure. That's why I'm asking for for documentation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation Issues describing a change to documentation. help wanted NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Development

No branches or pull requests

4 participants