Documentation
¶
Overview ¶
Package manifest reads and writes .gotools.json: the layout, the settings and the list of managed tools.
A Manifest holds file values only. Values resolved from the environment belong to package config, so an environment override is never written back. Parse accepts any valid JSON layout and ignores unknown keys; Render writes the layout committed files use, with a fixed key order and the tools sorted.
Example ¶
Parse reads any valid layout, Render writes the committed one, and Flush replaces the file atomically.
package main
import (
"fmt"
"os"
"path/filepath"
"github.com/piusalfred/gotools/internal/manifest"
)
func main() {
res, err := manifest.Parse([]byte(`{"strategy":"split","tools":{"gofumpt":{"source":"go","package":"mvdan.cc/gofumpt","version":"v0.9.2"}}}`), ".gotools.json")
fmt.Println(len(res.Warnings), err)
m := res.Manifest
m.SetTool(manifest.Tool{Name: "gci", Source: "go", Package: "github.com/daixiang0/gci", Version: "v0.14.0"})
dir, _ := os.MkdirTemp("", "manifest-example")
defer os.RemoveAll(dir)
path := filepath.Join(dir, ".gotools.json")
if err := m.Flush(path); err != nil {
fmt.Println(err)
}
back, _ := manifest.Load(path)
fmt.Println(back.Manifest.ToolNames())
}
Output: 0 <nil> [gci gofumpt]
Index ¶
- Constants
- Variables
- func CleanupTemps(path string)
- func FindRoot(start string) (root string, found bool)
- type Manifest
- func (m *Manifest) FindByPackage(pkg string) (string, bool)
- func (m *Manifest) Flush(path string) error
- func (m *Manifest) Get(key string) (string, bool)
- func (m *Manifest) RemoveTool(name string) bool
- func (m *Manifest) Render() ([]byte, error)
- func (m *Manifest) Set(key, value string) error
- func (m *Manifest) SetTool(t Tool)
- func (m *Manifest) SortedTools() []Tool
- func (m *Manifest) Tool(name string) (Tool, bool)
- func (m *Manifest) ToolNames() []string
- func (m *Manifest) Twin(name, pkg, version string, unified bool) (Tool, bool)
- func (m *Manifest) Twins(unified bool) [][]Tool
- type NewerSchemaError
- type ParseResponse
- type Status
- type Tool
Examples ¶
Constants ¶
const SchemaVersion = 1
SchemaVersion is the manifest schema this build understands. Bump it only when reading would misinterpret a newer format; additive changes do not need a bump.
Variables ¶
var ( // ErrMissing matches the error Load returns when there is no manifest. ErrMissing = errors.New("manifest not found") // ErrMalformed matches the error returned for truncated or malformed JSON. ErrMalformed = errors.New("manifest is not parseable: truncated or malformed JSON") )
Functions ¶
func CleanupTemps ¶
func CleanupTemps(path string)
CleanupTemps removes the temp files a crashed Flush left next to path.
Types ¶
type Manifest ¶
type Manifest struct {
Schema int
Strategy string
Dir string
GoVersion string
ModulePrefix string
Settings config.Settings
Tools []Tool
}
Manifest is the in-memory form of .gotools.json. Empty layout fields mean the file does not set them. Settings carries the defaults for keys the file leaves out, and Render writes them all.
func (*Manifest) FindByPackage ¶
FindByPackage returns the name of the first tool whose package is pkg.
func (*Manifest) Flush ¶
Flush writes the manifest atomically: a temp file created exclusively next to the target, so a pre-planted symlink cannot redirect the write, then renamed over it.
func (*Manifest) Get ¶
Get returns the file's value for a GOTOOLS_* key (config.Keys) and whether it is set. A layout key the file leaves out is not set; a settings key always has a value, the default when the file says nothing.
func (*Manifest) RemoveTool ¶
RemoveTool deletes a tool entry, reporting whether it existed.
func (*Manifest) Render ¶
Render produces the manifest bytes in the layout committed files use: fixed key order, 2-space indent, settings alphabetical, tools sorted by source, package, version and name. Layout fields the manifest leaves empty are written as their defaults, and the module prefix defaults to the directory.
func (*Manifest) Set ¶
Set applies value to a GOTOOLS_* key in memory, after checking it against what the key holds. A value that does not fit is a usage error and leaves the manifest unchanged; Flush writes it.
func (*Manifest) SortedTools ¶
SortedTools returns the tools in manifest order: source, package, version, then name.
func (*Manifest) Twin ¶
Twin reports another tool that is the same tool as (name, pkg, version): the same package, and either the same version or, when unified is true, any version. The unified strategy shares one go.mod, which holds a single version of a module, so a second name for a package can only be the same tool.
type NewerSchemaError ¶
type NewerSchemaError struct {
File string
Found int // the schema version in the file
Supported int // the schema version this build understands
}
NewerSchemaError reports a manifest written by a newer gotools. It is wrapped in an Environment error.
func (*NewerSchemaError) Error ¶
func (e *NewerSchemaError) Error() string
type ParseResponse ¶
type ParseResponse struct {
Manifest *Manifest
// Warnings are problems that did not stop the parse, such as a skipped tool
// entry with an unsafe name.
Warnings []string
}
ParseResponse is what Parse and Load return alongside the error.
func Load ¶
func Load(path string) (ParseResponse, error)
Load reads and parses the manifest at path. A missing file is an Environment error matching ErrMissing.
func Parse ¶
func Parse(data []byte, name string) (ParseResponse, error)
Parse decodes manifest bytes. It ignores unknown keys, skips tool entries with unsafe names (reported as warnings), and fills settings the file omits with their defaults. name only feeds error messages. Every error is an Environment error: ErrMalformed for bad JSON or a bad value, and a *NewerSchemaError for a newer schema.
Source Files