preferences

Documentation

Index

• Constants
• Variables
• func LoadApp[T any](app App[T]) (*T, error)
• func Save() error
• func SaveApp[T any](app App[T], prefs T) error
• type AgentPreferences
  • func (p *AgentPreferences) GetDescription(key string) string
  • func (p *AgentPreferences) GetValue(key string) (value any, found bool)
  • func (p *AgentPreferences) IsSecret(key string) bool
  • func (p *AgentPreferences) Keys() []string
  • func (p *AgentPreferences) Password() string
  • func (p *AgentPreferences) Server() string
  • func (p *AgentPreferences) SetValue(key string, value any) error
  • func (p *AgentPreferences) TopicPrefix() string
  • func (p *AgentPreferences) User() string
• type App
• type Preference
• type UI

Constants

const (
	PrefServer      = "mqtt.server"
	PrefUser        = "mqtt.user"
	PrefPassword    = "mqtt.password"
	PrefTopicPrefix = "mqtt.topicprefix"
)

Variables

var (
	ErrLoadPreferences     = errors.New("error loading preferences")
	ErrSavePreferences     = errors.New("error saving preferences")
	ErrValidatePreferences = errors.New("error validating preferences")
	ErrSetPreference       = errors.New("error setting preference")
)

Consistent error messages.

var (
	ErrSaveAppPrefs = errors.New("error saving app preferences")
	ErrLoadAppPrefs = errors.New("error loading app preferences")
)

var (
	Agent = &AgentPreferences{}
)

var (
	AppVersion = gitVersion
)

var ErrUnknownPref = errors.New("unknown preference")

var Load = func() error {
	return sync.OnceValue(func() error {
		slog.Debug("Loading preferences.", slog.String("file", filepath.Join(preferencesDir, preferencesFile)))

		if err := prefsSrc.Load(file.Provider(filepath.Join(preferencesDir, preferencesFile)), toml.Parser()); err != nil {
			return fmt.Errorf("%w: %w", ErrLoadPreferences, err)
		}

		if err := prefsSrc.Load(env.Provider(prefsEnvPrefix, ".", func(s string) string {
			return strings.Replace(strings.ToLower(
				strings.TrimPrefix(s, prefsEnvPrefix)), "_", ".", -1)
		}), nil); err != nil {
			return fmt.Errorf("%w: %w", ErrLoadPreferences, err)
		}

		return nil
	})()
}

Load will retrieve the current preferences from the preference file on disk. If there is a problem during retrieval, an error will be returned.

Functions

func LoadApp

func LoadApp[T any](app App[T]) (*T, error)

LoadApp reads the given apps's preferences from file.

func Save

func Save() error

Save will save the new values of the specified preferences to the existing preferences file. NOTE: if the preferences file does not exist, Save will return an error. Use New if saving preferences for the first time.

func SaveApp

func SaveApp[T any](app App[T], prefs T) error

SaveApp saves the given app's preferences to file.

Types

type AgentPreferences

type AgentPreferences struct{}

func (*AgentPreferences) GetDescription

func (p *AgentPreferences) GetDescription(key string) string

func (*AgentPreferences) GetValue

func (p *AgentPreferences) GetValue(key string) (value any, found bool)

func (*AgentPreferences) IsSecret

func (p *AgentPreferences) IsSecret(key string) bool

func (*AgentPreferences) Keys

func (p *AgentPreferences) Keys() []string

func (*AgentPreferences) Password

func (p *AgentPreferences) Password() string

func (*AgentPreferences) Server

func (p *AgentPreferences) Server() string

func (*AgentPreferences) SetValue

func (p *AgentPreferences) SetValue(key string, value any) error

func (*AgentPreferences) TopicPrefix

func (p *AgentPreferences) TopicPrefix() string

func (*AgentPreferences) User

func (p *AgentPreferences) User() string

type App

type App[T any] interface {
	PreferencesID() string
	DefaultPreferences() T
}

App represents an App from the point of the preferences package. An app has a set of default preferences returned by the DefaultPreferences method and an ID that uniquely identifies the app (and its preferences on disk).

type Preference

type Preference struct {
	// Value is the actual preference value.
	Value any `toml:"value"`
	// Description is a string that describes the preference, and may be used
	// for display purposes.
	Description string `toml:"description,omitempty"`
	// Secret is a flag that indicates whether this preference represents a
	// secret. The value has no effect on the preference encoding in the TOML,
	// only on how to display the preference to the user (masked or plaintext).
	Secret bool `toml:"-"`
}

Preference represents a single preference in a preferences file.

type UI

type UI interface {
	GetValue(key string) (any, bool)
	SetValue(key string, value any) error
	GetDescription(key string) string
	IsSecret(key string) bool
	Keys() []string
}

UI allows preferences to be exposed via a UI for the user to edit.