Documentation ¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
New is the primary entry point for using a constructor with a config.Loader. The given context and config.Loader are used for all lookups of configuration data. The given constructor must be a valid implementation of the Constructor protocol. The destination parameter must be assignable to the output of the constructor such as the output of new(T).
r := new(Result) err := New(context.Background(), source, &Constructor{}, r)
If the resulting error is nil then the destination value, r in this case, now points to the output of the Constructor.New method. The method returns an error any time the given constructor does not satisfy the contract, any time the configuration loading fails, or if the Constructor.New returns an error.
Types ¶
type Constructor ¶
type Constructor interface{}
Constructor is an empty interface meant only as a placeholder for the constructor protocol documentation.
The constructor protocol would have been defined here as an interface if Go supported generics. Until then, the interface exists only as documentation and reflection is used to validate and interact with implementations of the protocol.
A Constructor implementation is roughly equivalent to the Factory pattern. Each instance must expose two methods: Settings() and New(). The Settings() method must return a non-nil pointer to a struct that represents all of the configuration or input parameters required in order to construct an instance of the arbitrary type that the constructor intends to produce. Any values set in the returned struct will be treated as default values should a Loader be unable to find a user provided configuration for that field.
The output of Settings() must be the same type accepted as the second parameter of the New() method with the first parameter being a context.Context. The New() method must also return two values with the first being the type of the constructed value and the second being an error. For example, a pseudo-code interface might be:
type Constructor inteface{ Settings() *C New(ctx context.Context, conf *C) (*T, error) }
An example implementation of this might look like:
type MyConstructable struct {} type MyConfig struct{} type MyConstructor struct {} func(*MyConstructor) Settings() *MyConfig { return &MyConfig{} } func(*MyConstructor) New(ctx context.Context, conf *MyConfig) (*MyConstructable, error) { return &MyConstructable{}, nil }
This overall design is chosen maximize the decoupling of the configuration loading system from the constructors. Generally, all implementations of the constructor protocol are valid Go structs that in no way reference a specific system for loading. Each constructor can be used in code without importing the config project.