Documentation
¶
Overview ¶
Package format renders what a command reports as text or JSON.
A command builds a Document and hands it to a Formatter; it never branches on the output format itself. TextFormatter asks the document to write its text form, and JSONFormatter marshals the document as one JSON object carrying the output schema version. Select picks the formatter from the command line flags.
Index ¶
Examples ¶
Constants ¶
const SchemaVersion = 1
SchemaVersion is the "schema_version" carried by every JSON document. It is separate from the manifest schema version; bump it when a JSON output shape changes.
Variables ¶
var ErrConflict = ierrors.New(ierrors.Usage, "Conflicting output formats: use one of --format, --json or --text")
ErrConflict matches the error Select returns when the flags ask for two different formats.
Functions ¶
This section is empty.
Types ¶
type Document ¶
Document is what a command reports. Its json tags define the JSON form, and WriteText the text form.
type Failure ¶
type Failure struct {
Message string `json:"error"`
}
Failure is the document for a command that reports an error instead of its result: {"error": ...} as JSON, the bare message as text.
type Formatter ¶
type Formatter interface {
// Kind is the format the formatter writes.
Kind() Kind
// Write renders doc to w.
Write(w io.Writer, doc Document) error
}
Formatter writes a Document in one output format.
Example ¶
The formatters are interchangeable, so a caller can be handed either.
package main
import (
"fmt"
"os"
"github.com/piusalfred/gotools/internal/format"
)
func main() {
var f format.Formatter = format.JSONFormatter{}
fmt.Println(f.Kind())
_ = f.Write(os.Stdout, format.Failure{Message: "tool not found: gci"})
}
Output: json {"schema_version":1,"error":"tool not found: gci"}
func Select ¶
Select picks the formatter for the --format, --json and --text flags a command declares. name is the value of --format ("" when not given). Flags carry no order, so asking for two different formats is an error that matches ErrConflict, and not a question of which came last. With none given the default is text. An unknown format is a usage error.
Example ¶
A command reads its --format, --json and --text flags once, builds a document, and lets the formatter decide how it looks.
package main
import (
"fmt"
"io"
"os"
"github.com/piusalfred/gotools/internal/format"
)
type version struct {
Name string `json:"name"`
Version string `json:"version"`
}
func (v version) WriteText(w io.Writer) error {
_, err := fmt.Fprintf(w, "%s %s\n", v.Name, v.Version)
return err
}
func main() {
doc := version{Name: "gotools", Version: "v0.6.7"}
for _, json := range []bool{false, true} {
f, err := format.Select("", json, false)
if err != nil {
fmt.Println(err)
return
}
_ = f.Write(os.Stdout, doc)
}
}
Output: gotools v0.6.7 {"schema_version":1,"name":"gotools","version":"v0.6.7"}
type JSONFormatter ¶
type JSONFormatter struct{}
JSONFormatter is the Formatter for machine-readable output: one JSON object per document, on one line, starting with "schema_version". HTML characters stay readable and invalid UTF-8 is replaced instead of failing.
type TextFormatter ¶
type TextFormatter struct{}
TextFormatter is the Formatter for human-readable output.
Source Files