config

README

config

安装

go get github.com/issue9/config

版权

本项目采用 MIT 开源授权许可证，完整的授权说明可在 LICENSE 文件中找到。

Documentation

Overview

Package config 提供了对多种格式配置文件的支持

Index

• type Config
  • func AppDir(s Serializer, dir string) (*Config, error)
  • func BuildDir(s Serializer, dir string) (*Config, error)
  • func Dir(s Serializer, dir string) *Config
  • func New(s Serializer, dir string, parent func() (string, error)) (*Config, error)
  • func SystemDir(s Serializer, dir string) (*Config, error)
  • func WDDir(s Serializer, dir string) (*Config, error)
  • func (f *Config) Exists(name string) bool
  • func (f *Config) Load(name string, v any) error
  • func (f *Config) Read(name string) ([]byte, error)
  • func (f *Config) Root() *os.Root
  • func (f *Config) Save(name string, v any, mode fs.FileMode) error
  • func (f *Config) Serializer() Serializer
• type FieldError
  • func NewFieldError(field string, msg any) *FieldError
  • func (err *FieldError) AddFieldParent(prefix string) *FieldError
  • func (err *FieldError) Error() string
  • func (err *FieldError) LocaleString(p *localeutil.Printer) string
• type MarshalFunc
• type OpenFile
• type Sanitizer
• type Serializer
  • func (s Serializer) Add(m MarshalFunc, u UnmarshalFunc, ext ...string) Serializer
  • func (s Serializer) Delete(ext ...string)
  • func (s Serializer) Exists(ext string) bool
  • func (s Serializer) Get(ext string) (MarshalFunc, UnmarshalFunc)
  • func (s Serializer) GetByFilename(name string) (MarshalFunc, UnmarshalFunc)
  • func (s Serializer) Len() int
  • func (s Serializer) Marshal(f OpenFile, name string, v any, mode fs.FileMode) error
  • func (s Serializer) Unmarshal(f OpenFile, name string, v any) error
  • func (s Serializer) UnmarshalFS(fsys fs.FS, name string, v any) error
• type UnmarshalFunc

Types

type Config

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

Config 项目的配置文件管理

相对于 Serializer，Config 提供了对目录的保护，只能存储指定目录下的内容。

func AppDir

func AppDir(s Serializer, dir string) (*Config, error)

AppDir 将应用程序下的 dir 作为配置文件的保存目录

dir 相对 os.Executable 的目录名称；

func BuildDir

func BuildDir(s Serializer, dir string) (*Config, error)

BuildDir 根据 dir 生成不同的 Config

dir 为项目的配置文件目录，后续通过 Config 操作都被限制在此目录之下。可以带以下的特殊前缀：

• ~ 表示系统提供的配置文件目录，比如 Linux 的 XDG_CONFIG、Windows 的 AppData 等；
• @ 表示当前程序的主目录；
• ^ 表示绝对路径；
• # 表示工作路径，这是一个随着工作目录变化的值，使用时需要小心；
• 其它则是直接采用 Dir 初始化。

这是对 SystemDir、AppDir、Dir 和 WDDir 的合并处理。

func Dir

func Dir(s Serializer, dir string) *Config

Dir 以指定的目录作为配置文件的保存位置

func New

func New(s Serializer, dir string, parent func() (string, error)) (*Config, error)

New 声明 Config 对象

dir 表示当前项目的配置文件存放的目录名称，如果 parent 不为空，为相对于 parent 返回值的路径； parent 表示获取系统中用于存放配置文件的路径，比如 Linux 中的 XDG_CONFIG 等目录。 用户可以根据自己的需求自行实现该方法，如果为 nil，表示直接将 dir 作为全路径进行处理。

func SystemDir

func SystemDir(s Serializer, dir string) (*Config, error)

SystemDir 将系统提供的配置目录下的 dir 作为配置目录

dir 相对的 os.UserConfigDir 目录名称；

func WDDir

func WDDir(s Serializer, dir string) (*Config, error)

WDDir 将工作目录作为配置文件的保存目录

dir 相对 os.Getwd 的目录名称；

func (*Config) Exists

func (f *Config) Exists(name string) bool

Exists 是否存在指定的文件

func (*Config) Load

func (f *Config) Load(name string, v any) error

Load 加载指定名称的文件内容至 v

name 为文件名，相对于 Config.Root，根据文件扩展名决定采用什么编码方法； 如果 v 实现了 Sanitizer，在加载之后会调用该接口对数据进行处理；

func (*Config) Read

func (f *Config) Read(name string) ([]byte, error)

Read 读取文件的原始内容

func (*Config) Root

func (f *Config) Root() *os.Root

Root 配置文件的目录

func (*Config) Save

func (f *Config) Save(name string, v any, mode fs.FileMode) error

Save 将 v 解码并保存至 name 中

根据文件扩展名决定采用什么编码方法； mode 表示文件的权限，仅对新建文件时有效； 如果 v 实现了 Sanitizer，在保存之前会调用该接口对数据进行处理；

func (*Config) Serializer

func (f *Config) Serializer() Serializer

Serializer 返回管理配置文件序列化的对象

type FieldError

type FieldError struct {
	Path    string // 配置文件的路径
	Field   string // 字段名
	Message any    // 错误信息
	Value   any    // 字段的原始值
}

FieldError 表示配置内容字段错误

func NewFieldError

func NewFieldError(field string, msg any) *FieldError

NewFieldError 返回表示配置文件错误的对象

field 表示错误的字段名； msg 表示错误信息，可以是任意类型，如果类型为 FieldError，那么将调用 msg.AddFieldParent(field)；

func (*FieldError) AddFieldParent

func (err *FieldError) AddFieldParent(prefix string) *FieldError

AddFieldParent 为字段名加上一个前缀

当字段名存在层级关系时，外层在处理错误时，需要为其加上当前层的字段名作为前缀。

func (*FieldError) Error

func (err *FieldError) Error() string

func (*FieldError) LocaleString

func (err *FieldError) LocaleString(p *localeutil.Printer) string

type MarshalFunc

type MarshalFunc func(any) ([]byte, error)

type OpenFile

type OpenFile func(name string, flag int, perm fs.FileMode) (*os.File, error)

type Sanitizer

type Sanitizer interface {
	// SanitizeConfig 验证当前对象的数据
	//
	// NOTE: 如果当前对象是个结构体，
	// 需要接口的实现自行判断和调用各个字段 [Sanitizer] 接口。
	SanitizeConfig() *FieldError
}

Sanitizer 对配置文件的数据验证和修正

type Serializer

type Serializer map[string]*serializer

Serializer 管理配置文件序列化的方法

根据配置文件的扩展查找相应的序列化方法， 扩展名必须以 . 开头，如果未带 .，则会自动加上。

func (Serializer) Add

func (s Serializer) Add(m MarshalFunc, u UnmarshalFunc, ext ...string) Serializer

Add 添加新的序列方法

ext 为文件扩展名，需要带 . 符号；

func (Serializer) Delete

func (s Serializer) Delete(ext ...string)

Delete 删除序列化方法

func (Serializer) Exists

func (s Serializer) Exists(ext string) bool

Exists 是否存在对指定扩展名的序列化方法

func (Serializer) Get

func (s Serializer) Get(ext string) (MarshalFunc, UnmarshalFunc)

Get 获取指定扩展名对应的序列化方法

如果不存在，则返回 nil。

func (Serializer) GetByFilename

func (s Serializer) GetByFilename(name string) (MarshalFunc, UnmarshalFunc)

GetByFilename 通过文件查找对应的序列化方法

func (Serializer) Len

func (s Serializer) Len() int

func (Serializer) Marshal

func (s Serializer) Marshal(f OpenFile, name string, v any, mode fs.FileMode) error

Marshal 将 v 按 name 的后缀名序列化并保存

func (Serializer) Unmarshal

func (s Serializer) Unmarshal(f OpenFile, name string, v any) error

Unmarshal 根据 name 后缀名序列化其内容至 v

func (Serializer) UnmarshalFS

func (s Serializer) UnmarshalFS(fsys fs.FS, name string, v any) error

UnmarshalFS 根据 name 后缀名序列化其内容至 v

type UnmarshalFunc

type UnmarshalFunc func([]byte, any) error