settings

package module
v1.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 4, 2025 License: Apache-2.0 Imports: 23 Imported by: 5

Documentation

Overview

Package settings is like a Swiss Army knife for handling app configurations in Go. It's designed to make your life easier when dealing with all sorts of settings - think of it as your go-to toolkit for configuration management.

Here's the lowdown on what this package brings to the table:

  • Marshaller and Unmarshaller: These interfaces are your friends for transforming settings to and from byte slices. They're super handy for storage or network transmission.
  • String, Bool, Int, Uint etc.: Meet the fundamental building blocks for your settings.
  • Blueprint: This is the brains of the operation. It lets you define and manage settings schemas, validate inputs, and even extend configurations with more settings.
  • Schema: This is the blueprint's state. It's a collection of settings that can be compiled into a schema to store schema version. It also provides a way to create profiles.
  • Profile: Think of it as your settings' memory. It keeps track of user preferences and application settings, making sure everything's in place and up-to-date.
  • Preferences: This is the profile's state. It's a collection of settings that can be compiled into a profile to store user preferences.
  • Reflective Magic: We use reflection (responsibly!) to dynamically handle fields in your structs. This means less boilerplate and more action.

Index

Constants

View Source 
const (
	KindSettings = Kind(vars.KindInterface)
	KindCustom   = Kind(vars.KindByteSlice)

	KindInvalid     = Kind(vars.KindInvalid)
	KindBool        = Kind(vars.KindBool)
	KindInt         = Kind(vars.KindInt)
	KindUint        = Kind(vars.KindUint)
	KindString      = Kind(vars.KindString)
	KindDuration    = Kind(vars.KindDuration)
	KindStringSlice = Kind(vars.KindSlice)
)

Variables

View Source 
var (
	Error          = errors.New("settings")
	ErrSetting     = errors.New("setting")
	ErrProfile     = fmt.Errorf("%w: profile", Error)
	ErrPreferences = fmt.Errorf("%w: preferences", Error)
	ErrSpec        = errors.New("spec error")
)
View Source 
var (
	ErrBlueprint = errors.New("settings blueprint")
)
View Source 
var (
	ErrSchema = errors.New("schema")
)

Functions

func UnmarshalValue added in v0.7.0 

func UnmarshalValue[T Value](data []byte, v T) error

Types

type Blueprint 

type Blueprint struct {
	// contains filtered or unexported fields
}

func New 

func New[S Settings](s S) (*Blueprint, error)

func (*Blueprint) AddSpec 

func (b *Blueprint) AddSpec(spec SettingSpec) error

func (*Blueprint) AddValidator 

func (b *Blueprint) AddValidator(key, desc string, fn func(s Setting) error)

func (*Blueprint) Describe 

func (b *Blueprint) Describe(key string, lang language.Tag, description string)

func (*Blueprint) Extend 

func (b *Blueprint) Extend(group string, ext Settings) (err error)

func (*Blueprint) GetSpec 

func (b *Blueprint) GetSpec(key string) (SettingSpec, error)

func (*Blueprint) Migrate 

func (b *Blueprint) Migrate(keyfrom, keyto string) error

func (*Blueprint) PackageSettingsStructName added in v0.6.0 

func (b *Blueprint) PackageSettingsStructName() string

func (*Blueprint) Schema 

func (b *Blueprint) Schema(module string, version version.Version) (Schema, error)

func (*Blueprint) SetDefault 

func (b *Blueprint) SetDefault(key string, value Value) error

func (*Blueprint) SetDefaultFromString added in v0.6.0 

func (b *Blueprint) SetDefaultFromString(key string, value string) error

type Bool 

type Bool bool

Bool represents a setting type based on a boolean.

func (Bool) MarshalSetting 

func (b Bool) MarshalSetting() ([]byte, error)

MarshalSetting converts the Bool setting to a byte slice, representing "true" or "false".

func (Bool) SettingKind 

func (b Bool) SettingKind() Kind

func (Bool) String 

func (b Bool) String() string

func (*Bool) UnmarshalSetting 

func (b *Bool) UnmarshalSetting(data []byte) error

UnmarshalSetting updates the Bool setting from a byte slice, interpreting it as "true" or "false".

type Duration 

type Duration time.Duration

func (Duration) MarshalSetting 

func (d Duration) MarshalSetting() ([]byte, error)

func (Duration) SettingKind 

func (d Duration) SettingKind() Kind

func (Duration) String 

func (d Duration) String() string

func (*Duration) UnmarshalSetting 

func (d *Duration) UnmarshalSetting(data []byte) error

type ExecutionMode 

type ExecutionMode int

executionMode determines the context in which the application is running. 

const (
	ModeUnknown    ExecutionMode = 1 << iota // Unknown mode
	ModeProduction                           // Running as a compiled binary
	ModeDevel                                // Running with `go run`
	ModeTesting                              // Running in a test context
)

func (ExecutionMode) MarshalText 

func (e ExecutionMode) MarshalText() ([]byte, error)

func (ExecutionMode) String 

func (e ExecutionMode) String() string

func (*ExecutionMode) UnmarshalText 

func (e *ExecutionMode) UnmarshalText(data []byte) error

type Int 

type Int int

Int represents a setting type based on an integer.

func (Int) MarshalSetting 

func (i Int) MarshalSetting() ([]byte, error)

MarshalSetting converts the Int setting to a byte slice for storage or transmission.

func (Int) SettingKind 

func (i Int) SettingKind() Kind

func (Int) String 

func (i Int) String() string

func (*Int) UnmarshalSetting 

func (i *Int) UnmarshalSetting(data []byte) error

UnmarshalSetting updates the Int setting from a byte slice, interpreting it as an integer.

type Kind 

type Kind uint8

func (Kind) String 

func (k Kind) String() string

type Marshaller 

type Marshaller interface {
	MarshalSetting() ([]byte, error)
}

Marshaller interface for marshaling settings

type Mutability 

type Mutability uint8
const (
	// SettingImmutable can not be changed on runtime.
	SettingImmutable Mutability = 254
	// SettingOnce can be set only once on runtime.
	// When changed typically requires a reload of application.
	SettingOnce Mutability = 253
	// SettingMutable can be changed on runtime.
	SettingMutable Mutability = 252
)

func (Mutability) String 

func (m Mutability) String() string

type Preferences 

type Preferences struct {
	// contains filtered or unexported fields
}

func NewPreferences 

func NewPreferences(schemaVersion version.Version) *Preferences

func (*Preferences) GobDecode added in v0.6.0 

func (p *Preferences) GobDecode(data []byte) error

func (Preferences) GobEncode added in v0.6.0 

func (p Preferences) GobEncode() ([]byte, error)

func (*Preferences) SchemaVersion added in v0.6.0 

func (p *Preferences) SchemaVersion() version.Version

func (*Preferences) Set 

func (p *Preferences) Set(key, value string)

func (*Preferences) UnmarshalJSON added in v0.6.0 

func (p *Preferences) UnmarshalJSON(b []byte) error

type Profile 

type Profile struct {
	// contains filtered or unexported fields
}

func (*Profile) All 

func (p *Profile) All() iter.Seq[Setting]

func (*Profile) Changed added in v0.6.0 

func (p *Profile) Changed() bool

func (*Profile) Get 

func (p *Profile) Get(key string) Setting

func (*Profile) Has 

func (p *Profile) Has(key string) bool

func (*Profile) Lang 

func (p *Profile) Lang() language.Tag

func (*Profile) Loaded 

func (p *Profile) Loaded() bool

Loaded reports true when settings profile is loaded and optional user preferences are applied.

func (*Profile) Module 

func (p *Profile) Module() string

func (*Profile) Name 

func (p *Profile) Name() string

func (*Profile) PackageSettingsStructName added in v0.6.0 

func (p *Profile) PackageSettingsStructName() string

func (*Profile) Preferences added in v0.6.0 

func (p *Profile) Preferences() *Preferences

Preferences returns the profile's preferences which can be saved.

func (*Profile) Set 

func (p *Profile) Set(key string, val any) (err error)

func (*Profile) ValidatePreference added in v0.6.0 

func (p *Profile) ValidatePreference(key string, val any) (err error)

func (*Profile) Version 

func (p *Profile) Version() version.Version

type Schema 

type Schema struct {
	// contains filtered or unexported fields
}

func (*Schema) Profile 

func (s *Schema) Profile(name string, pref *Preferences) (*Profile, error)

type Setting 

type Setting struct {
	// contains filtered or unexported fields
}

func (Setting) Default added in v0.2.0 

func (s Setting) Default() vars.Variable

func (Setting) Description 

func (s Setting) Description() string

func (Setting) Display added in v0.7.0 

func (s Setting) Display() string

Display returns the translated value for display purposes. If the setting uses i18n and i18n is initialized, it returns the translated string. Otherwise, it returns the raw value (same as String()). For Persistent settings that are user-defined (isSet=true), i18n is not applied.

func (Setting) I18nKey added in v1.0.0 

func (s Setting) I18nKey() string

I18nKey returns the i18n key for this setting, or empty string if not using i18n.

func (Setting) IsI18n added in v1.0.0 

func (s Setting) IsI18n() bool

IsI18n returns true if this setting uses i18n translation.

func (Setting) IsSecret added in v1.1.0 

func (s Setting) IsSecret() bool

IsSecret reports whether this setting has been marked as secret via struct tag. Secrets are intended to be redacted by higher-level tooling (e.g. CLI config commands).

func (Setting) IsSet 

func (s Setting) IsSet() bool

func (Setting) Key 

func (s Setting) Key() string

func (Setting) Kind 

func (s Setting) Kind() Kind

func (Setting) Mutability 

func (s Setting) Mutability() Mutability

func (Setting) Persistent 

func (s Setting) Persistent() bool

func (Setting) String 

func (s Setting) String() string

func (Setting) Value 

func (s Setting) Value() vars.Variable

type SettingSpec 

type SettingSpec struct {
	IsSet       bool
	Kind        Kind
	Key         string
	Default     string
	Mutability  Mutability
	Value       string
	Required    bool
	Persistent  bool
	Unmarchaler Unmarshaller
	Marchaler   Marshaller
	Settings    *Blueprint
	Secret      bool // true if field has secret:"true" tag
	// contains filtered or unexported fields
}

func (SettingSpec) Setting 

func (s SettingSpec) Setting(lang language.Tag) (Setting, error)

func (SettingSpec) Validate 

func (s SettingSpec) Validate() error

func (SettingSpec) ValidateValue 

func (s SettingSpec) ValidateValue(value string) error

type Settings 

type Settings interface {
	Blueprint() (*Blueprint, error)
}

SettingKind() Kind

type String 

type String string

String represents a setting type based on a string.

func (*String) MarshalSetting 

func (s *String) MarshalSetting() ([]byte, error)

MarshalSetting converts the String setting to a byte slice for storage or transmission.

func (String) SettingKind 

func (s String) SettingKind() Kind

SettingKind returns the kind of setting

func (String) String 

func (s String) String() string

Stringer implementation for String type

func (*String) UnmarshalSetting 

func (s *String) UnmarshalSetting(data []byte) error

UnmarshalSetting updates the String setting from a byte slice, typically read from storage or received in a message.

type StringSlice 

type StringSlice []string

func (StringSlice) MarshalSetting 

func (ss StringSlice) MarshalSetting() ([]byte, error)

func (StringSlice) SettingKind 

func (ss StringSlice) SettingKind() Kind

func (StringSlice) String 

func (ss StringSlice) String() string

func (*StringSlice) UnmarshalSetting 

func (ss *StringSlice) UnmarshalSetting(data []byte) error

type Uint 

type Uint uint

Uint represents a setting type based on an unsigned integer.

func (Uint) MarshalSetting 

func (u Uint) MarshalSetting() ([]byte, error)

MarshalSetting converts the Uint setting to a byte slice for storage or transmission.

func (Uint) SettingKind 

func (u Uint) SettingKind() Kind

func (Uint) String 

func (u Uint) String() string

func (*Uint) UnmarshalSetting 

func (u *Uint) UnmarshalSetting(data []byte) error

UnmarshalSetting updates the Uint setting from a byte slice, interpreting it as an unsigned integer.

type Unmarshaller 

type Unmarshaller interface {
	UnmarshalSetting([]byte) error
}

Unmarshaller interface for unmarshaling settings

type Value added in v0.6.0 

type Value interface {
	fmt.Stringer
	Marshaller
	Unmarshaller
}

Value interface that combines multiple interfaces

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.