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.

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/809751e636ae1230134d11983523ec5d8a2b24e6/example/main.go#L1-L57

Output:

• Usage

 .\test.exe -?
flag provided but not defined: -?
shouchan example
  - addr: employee address
        default:defAddrPointer
  - employer-name: company name
        default:defCom
  - ipaddr: employee IP address
        default:1.2.3.4
  - jointtime: employee join time
        default:2023-01-02 13:22:33
  - mac: employee MAC address
        default:11:22:33:44:55:66
  - n2addr:
        default:1.1.1.1
  - naddr:
        default:2.2.2.2
  - name: employee name
        default:defName
  - subnet: employee IP subnet
        default:192.168.1.0/24

  -cfgfromfile: load configuration from the specified file
        default:test.yaml

• 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[T any](def T, name, usage string, options ...SconfOption[T]) (*SConf[T], error)
  • func (cnf *SConf[T]) GetConf() T
  • func (cnf *SConf[T]) GetConfAny() any
  • func (cnf *SConf[T]) MarshalYAML() ([]byte, error)
  • func (cnf *SConf[T]) PrintUsage()
  • func (cnf *SConf[T]) Read(args []string) (ferr, aerr error)
  • func (cnf *SConf[T]) ReadwithCMDLine() (ferr, aerr error)
  • func (cnf *SConf[T]) UnmarshalYAML(buf []byte) error
  • func (cnf *SConf[T]) UsageStr(prefix string) string
• type SConfInt
• type SconfOption
  • func WithConfigFileFlagName[T any](name string) SconfOption[T]
  • func WithDefaultConfigFilePath[T any](def string) SconfOption[T]
  • func WithFillFlags[T any](fill bool) SconfOption[T]
  • func WithFillOptions[T any](optlist []myflags.FillerOption) SconfOption[T]
• 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[T any] struct {
	// contains filtered or unexported fields
}

SConf represents a set of configurations as a struct

func NewSConf

func NewSConf[T any](def T, name, usage string, options ...SconfOption[T]) (*SConf[T], 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[T]) GetConf

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

GetConf returns config value

func (*SConf[T]) GetConfAny

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

func (*SConf[T]) MarshalYAML

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

MarshalYAML marshal config value into YAML

func (*SConf[T]) PrintUsage

func (cnf *SConf[T]) PrintUsage()

func (*SConf[T]) Read

func (cnf *SConf[T]) Read(args []string) (ferr, aerr error)

Read read configuration first from file, then flagset from args, flagset will be read regardless if file read succeds, ferr is error of file reading, aerr is error of flagset 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[T]) ReadwithCMDLine

func (cnf *SConf[T]) ReadwithCMDLine() (ferr, aerr error)

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

func (*SConf[T]) UnmarshalYAML

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

UnmarshalYAML unmrshal YAML encoded buf into config value

func (*SConf[T]) UsageStr

func (cnf *SConf[T]) UsageStr(prefix string) string

type SConfInt

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

type SconfOption

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

func WithConfigFileFlagName

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

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

func WithDefaultConfigFilePath

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

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

func WithFillFlags

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

WithFillFlags specifies whether to fill flags

func WithFillOptions

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

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