qmk-rgb/cmd/qmk-rgb-tool/datadir.go

package main

import (
	"os"
	"path/filepath"
	"strings"

	intrgb "netdome.biz/paul/qmk-rgb/internal/rgb"
)

// The tool's own files live under one directory per platform, the one
// os.UserConfigDir names, so they are the same on Linux, macOS and Windows and a
// hardcoded ~/.config is not.
//
// There is one such directory and both kinds of file are read from it and
// written to it. There used to be a search: definitions and profiles were looked
// for next to the executable and in the working directory before the user's, and
// that was wrong for both. A definition is written by `keyboard fetch` and read
// by every command, so a search path can hide the file the user just fetched. A
// profile is written to the user's directory, so a search path for reading can
// find a same-named file in a checkout instead and load that one — the same name,
// different content, and which one you get depends on where you stand.
//
// One argument reaches a file outside it: a profile argument ending in .json is a
// path, and `load profiles/lava.json` reads that file. That is the user naming the
// file rather than a directory being searched, so it does not reintroduce either
// defect above — the argument is the same in every working directory and names
// one file either way.
const dataDirName = "qmk-rgb-tool"

// userConfigDir is a seam: os.UserConfigDir is the platform's own answer, and a
// test cannot rely on which platform it runs on.
var userConfigDir = os.UserConfigDir

// The overrides short-circuit the lookup, which is how the tests point a lookup
// at a temporary directory. Empty means resolve it. Each directory has its own
// because the directories are separate, and a test that exercises one of them is
// not thereby exercising another.
var (
	profilesDirOverride    string
	definitionsDirOverride string
	namesDirOverride       string
)

// userDataDir is this tool's directory under the platform's configuration
// directory: ~/.config/qmk-rgb-tool on Linux, ~/Library/Application
// Support/qmk-rgb-tool on macOS, %AppData%\qmk-rgb-tool on Windows. A hardcoded
// ~/.config would be wrong on two of the three.
func userDataDir() string {
	base, err := userConfigDir()
	if err != nil || base == "" {
		return dataDirName
	}
	return filepath.Join(base, dataDirName)
}

// definitionsPath is where the definition files live: the per-user directory,
// and nowhere else. A `keyboard fetch` writes here, so anything else would mean
// the file a fetch produced is not the file the next command reads. The
// definitions built into the binary are consulted after this one, by
// candidateDefinitions in catalog.go.
func definitionsPath() string {
	if definitionsDirOverride != "" {
		return definitionsDirOverride
	}
	return filepath.Join(userDataDir(), intrgb.DefinitionsDir)
}

// profilesPath is where the profiles live: the per-user directory, and nowhere
// else. Reading and writing are the same place, so `save lava` followed by
// `load lava` finds what was just written, and a same-named file in a checkout
// cannot be loaded in place of it. An argument ending in .json never comes here —
// resolveProfileTarget in profile.go is where the rule is, and it sends a name to
// this directory and a path to the file system.
func profilesPath() string {
	if profilesDirOverride != "" {
		return profilesDirOverride
	}
	return filepath.Join(userDataDir(), "profiles")
}

// ensureDataDir returns a directory and creates it, for the commands that write.
func ensureDataDir(path string) (string, error) {
	if err := os.MkdirAll(path, 0o755); err != nil {
		return "", err
	}
	return path, nil
}

// describeDataDir annotates a path so a message that names one says which place
// it is: every directory this tool writes to is under the user's, and a bare
// path does not say that.
func describeDataDir(path string) string {
	if user := userDataDir(); path == user || strings.HasPrefix(path, user+string(filepath.Separator)) {
		return path + " (your user directory)"
	}
	return path
}