shouchan

README

Overview

Package shouchan provides simple configuration management for Golang application, with following features:

• read configuration from command line flag and/or YAML file, mix&match, into a struct
• 3 sources: default value, YAML file and flag
• priority:in case of multiple source returns same config struct field, the preference is flag over YAML over default value

include support following field types:

• integer types
• float type
• string
• time.Duration
• and all types that implement encoding.TextMarshaler and encoding.TextUnmarshaler interface
• there is also github.com/hujun-open/shouchantypes include some other types

Additional types could be supported by using Register, see github.com/hujun-open/shouchantypes for example.

curent release is github.com/hujun-open/shouchan/v2

CLI & YAML Support

• YAML: shouchan uses extyaml for YAML marshal and unmarshal
• CLI Flag: shouchan uses myflags for command line flag generation

refer to corresponding doc for details on CLI & YAML support.

Example:

https://github.com/hujun-open/shouchan/blob/6d6eda8b423d48cd7461804b4beb5c7693b6c3ba/example/main.go#L1-L63

Output:

• Usage

  .\test.exe --help
shouchan example

Usage:
  example [flags]

Flags:
      --addr string            employee address (default "defAddrPointer")
      --cfgfromfile string     config file path (default "test.yaml")
      --employer-name string   company name (default "defCom")
  -h, --help                   help for example
      --ipaddr net.IP          employee IP address (default 1.2.3.4)
      --jointtime time.Time    employee join time (default 2023-01-02 13:22:33)
      --mac net.HardwareAddr   employee MAC address (default 11:22:33:44:55:66)
      --n2addr                  (default 1.1.1.1)
      --naddr                   (default 2.2.2.2)
      --name string            employee name (default "defName")
      --r                      retired
      --subnet net.IPNet       employee IP subnet (default 192.168.1.0/24)
ferr failed to open config file test.yaml, open test.yaml: The system cannot find the file specified.,aerr <nil>
final result is &{Name:defName Addr:0xc000028ee0 Naddr:2.2.2.2 N2addr:1.1.1.1 IPAddr:1.2.3.4 Subnet:{IP:192.168.1.0 Mask:ffffff00} MAC:11:22:33:44:55:66 JointTime:2023-01-02 13:22:33 +0000 UTC IsRetired:false Employer:{Name:defCom}}

• no command line args, no config file, default is used

 .\test.exe   
ferr failed to open config file test.yaml, open test.yaml: The system cannot find the file specified.,aerr <nil>
final result is &{Name:defName Addr:0xc0000528b0 Naddr:2.2.2.2 N2addr:1.1.1.1 IPAddr:1.2.3.4 Subnet:{IP:192.168.1.0 Mask:ffffff00} MAC:11:22:33:44:55:66 JointTime:2023-01-02 13:22:33 +0000 UTC Employer:{Name:defCom}}

• config file via "-f" command args, value from file take procedence

 .\test.exe --cfgfromfile cfg.yaml
ferr <nil>,aerr <nil>
final result is &{Name:nameFromFile Addr:0xc0000528b0 Naddr:2.2.2.2 N2addr:1.1.1.1 IPAddr:1.2.3.4 Subnet:{IP:192.168.1.0 Mask:ffffff00} MAC:11:22:33:44:55:66 JointTime:2023-01-02 13:22:33 +0000 UTC Employer:{Name:comFromFile}}

• mix command line args and config file, args to override employee name:

.\test.exe --cfgfromfile cfg.yaml --name nameFromArg
ferr <nil>,aerr <nil>
final result is &{Name:nameFromArg Addr:0xc000088880 Naddr:2.2.2.2 N2addr:1.1.1.1 IPAddr:1.2.3.4 Subnet:{IP:192.168.1.0 Mask:ffffff00} MAC:11:22:33:44:55:66 JointTime:2023-01-02 13:22:33 +0000 UTC Employer:{Name:comFromFile}}

• mix command line args and config file, args to override company name:

.\test.exe --cfgfromfile cfg.yaml --employer-name comFromArg
ferr <nil>,aerr <nil>
final result is &{Name:nameFromFile Addr:0xc000104880 Naddr:2.2.2.2 N2addr:1.1.1.1 IPAddr:1.2.3.4 Subnet:{IP:192.168.1.0 Mask:ffffff00} MAC:11:22:33:44:55:66 JointTime:2023-01-02 13:22:33 +0000 UTC Employer:{Name:comFromArg}}

Code Generation

shouchan also provides a code generation tool to deal with large amount of constants, see shouchangen.

Documentation

Index

• Constants
• func Register[T any](to ToStr, from FromStr)
• type FromStr
• type SConf
  • func NewSConf[X any](def *X, name, usage string, options ...SconfOption[X]) (*SConf[X], error)
  • func (cnf *SConf[X]) GetConf() *X
  • func (cnf *SConf[X]) GetConfAny() any
  • func (cnf *SConf[X]) MarshalYAML() ([]byte, error)
  • func (cnf *SConf[X]) Read(args []string) (cmd *cobra.Command, ferr, aerr error)
  • func (cnf *SConf[X]) ReadwithCMDLine() (cmd *cobra.Command, ferr, aerr error)
  • func (cnf *SConf[X]) UnmarshalYAML(buf []byte) error
• type SConfInt
• type SconfOption
  • func WithConfigFileFlagName[X any](name string) SconfOption[X]
  • func WithDefaultConfigFilePath[X any](def string) SconfOption[X]
  • func WithFillFlags[X any](fill bool) SconfOption[X]
  • func WithFillOptions[X any](optlist []myflags.FillerOption) SconfOption[X]
• type ToStr

Constants

const (
	DefCfgFileFlagName = "cfgfromfile"
)

Functions

func Register

func Register[T any](to ToStr, from FromStr)

Register type T with provided to and from functions

Types

type FromStr

type FromStr func(s string) (any, error)

FromStr is the function convert a string into a instance of to-be-supported-type

type SConf

type SConf[X any] struct {
	Filler *myflags.Filler
	// contains filtered or unexported fields
}

SConf represents a set of configurations as a struct

func NewSConf

func NewSConf[X any](def *X, name, usage string, options ...SconfOption[X]) (*SConf[X], error)

NewSConf returns a new SConf instance, def is a pointer to configruation struct with default value, defpath is the default configuration file path, it could be overriden by using command line arg "-f", could be "" means no default path

func (*SConf[X]) GetConf

func (cnf *SConf[X]) GetConf() *X

GetConf returns config value

func (*SConf[X]) GetConfAny

func (cnf *SConf[X]) GetConfAny() any

func (*SConf[X]) MarshalYAML

func (cnf *SConf[X]) MarshalYAML() ([]byte, error)

MarshalYAML marshal config value into YAML

func (*SConf[X]) Read

func (cnf *SConf[X]) Read(args []string) (cmd *cobra.Command, ferr, aerr error)

Read read configuration first from file, then from commandline args, commandline args will be read regardless if file read succeds, cmd is the command get executed, ferr is error of file reading, aerr is error of commandline args reading. if there is ferr and/or aerr, it could be treated as non-fatal failure thanks to mix&match and priority support.

func (*SConf[X]) ReadwithCMDLine

func (cnf *SConf[X]) ReadwithCMDLine() (cmd *cobra.Command, ferr, aerr error)

ReadCMDLine is same as Read, expcept the args is os.Args[1:]

func (*SConf[X]) UnmarshalYAML

func (cnf *SConf[X]) UnmarshalYAML(buf []byte) error

UnmarshalYAML unmrshal YAML encoded buf into config value

type SConfInt

type SConfInt interface {
	GetConfAny() any
	UsageStr(prefix string) string
	// contains filtered or unexported methods
}

type SconfOption

type SconfOption[X any] func(ec *SConf[X])

func WithConfigFileFlagName

func WithConfigFileFlagName[X any](name string) SconfOption[X]

WithConfigFileFlagName sepcifies the flag name of loading config file, default is defined by const DefCfgFileFlagName

func WithDefaultConfigFilePath

func WithDefaultConfigFilePath[X any](def string) SconfOption[X]

WithDefaultConfigFilePath specifies default config file path, if it is empty, then there is no reading from config file

func WithFillFlags

func WithFillFlags[X any](fill bool) SconfOption[X]

WithFillFlags specifies whether to fill flags

func WithFillOptions

func WithFillOptions[X any](optlist []myflags.FillerOption) SconfOption[X]

WithFillOptions specifies options used to create myflags.Filler

type ToStr

type ToStr func(in any) (string, error)

ToStr is the function convert a instance of to-be-supported-type into string