simple

Documentation

Overview

simple package is a simple but opinionated package that combines common chores for server startup into a single package. It is still highly flexible based on the application's needs and keeps the dependencies as low as possible.

• processing command line input
• providing a default configuration
• providing a way for users to discover configuration documentation
• providing a place for storing build details
• unopinionated about decoders ... you must specify your own
• opinionated about encoders ... you will get a yaml encoder

See the example for how to use this package in your code.

Example

// SPDX-FileCopyrightText: 2022 Weston Schmidt <weston_schmidt@alumni.purdue.edu>
// SPDX-License-Identifier: Apache-2.0

package main

import (
	"fmt"
	"os"

	"github.com/schmidtw/goschtalt"
	"github.com/schmidtw/goschtalt/extensions/cli/simple"
	"github.com/schmidtw/goschtalt/pkg/decoder"

	// Uncomment the next line to use the yaml decoder automatically.
	//_ "github.com/schmidtw/goschtalt/extensions/decoders/yaml"
	"github.com/schmidtw/goschtalt/pkg/meta"
)

// This is a fake decoder that allows the example to work without the need
// to bring any external decoders in.
type fake struct{}

func (f fake) Decode(_ decoder.Context, _ []byte, _ *meta.Object) error { return nil }
func (f fake) Extensions() []string                                     { return []string{"yml"} }

func alterArgs() {
	os.Args = []string{"example", "--kvp", "Example.color", "blue", "--kvp", "Muppet", "fozzie"}

	// Uncomment the next line to output all the configuration values.
	// os.Args = append(os.Args, "-s")
}

func register() goschtalt.Option {
	// Change the line below to return nil to use the yml decoder
	return goschtalt.RegisterDecoder(fake{})
}

func main() {
	alterArgs() // This makes the function act like the command line.

	// Create a default configuration with all the options listed, documented,
	// and set to the default value, so the end user can ask the program for the
	// document.  It's ok to leave large sections commented out, too.
	defaults := simple.DefaultConfig{
		Text: `---
Example:
  # color can be one of [ red, green, blue ]
  color: blue # a popular color
`,
		Ext: "yml",
	}

	p := simple.Program{
		Name:    "example",
		Default: defaults,
	}

	g, err := p.GetConfig(register())
	if g == nil { // We've been told to exit.
		if err != nil { // There was an error.
			panic(err)
		}
		// No error, just gracefully exit.
		return
	}

	// Now let's us the configuration...

	var s string
	s, _ = goschtalt.Fetch[string](g, "example.color")
	fmt.Println(s)

	s, _ = goschtalt.Fetch[string](g, "muppet")
	fmt.Println(s)

}

Output:

blue
fozzie

Index

• Variables
• type DefaultConfig
• type Program
  • func (p Program) GetConfig(opts ...goschtalt.Option) (*goschtalt.Config, error)

Examples

• Package

Variables

var (
	GitCommit = "undefined" // The git commit hash of the source the program was built from.
	Version   = "undefined" // The version of the program.
	BuildTime = "undefined" // The time the program was built.
)

Use the -ldflags command line option to set the values of these three values at build time. These values are produced upon request from the command line interface upon request.

Example:

go build -ldflags "\
	-X 'simple.BuildTime=$(date --rfc-3339=seconds)' \
	-X 'simple.Version=v1.2.3' \
	-X 'simple.GitCommit=abc1234'"

var (
	ErrDefaultConfigInvalid = errors.New("default config invalid")
)

Types

type DefaultConfig

type DefaultConfig struct {
	Text string // The text of the default configuration.
	Ext  string // The extension of the default configuration.
}

DefaultConfig defines the built in configuration document and extension.

type Program

type Program struct {
	Name      string        // Required - name of the application
	Default   DefaultConfig // Required - default configuration
	Prefix    string        // Optional - defaults to strings.ToUpper(Name)+"_" if empty
	Licensing string        // Optional - if you want to include licensing details and option
	Output    io.Writer     // Optional - defaults to os.Stderr

	// An optional map of label to struct that will be used to validate
	// the default configuration against.  The configuration is validated if
	// exactly the same number of fields in the struct matches the fields in
	// the configuration (honoring mapstruct instructions).  No more or no
	// fewer are permitted.  This validation will be done at program start
	// unless explicitly instructed to skip via the --skip-validation option
	// is passed.
	//
	// Why provide this map?  This helps ensure your configuration documentation
	// and your program are close, if not the same.  If there are areas that
	// does not fit into this model well, feel free to leave them out.
	Validate map[string]any
}

func (Program) GetConfig

func (p Program) GetConfig(opts ...goschtalt.Option) (*goschtalt.Config, error)

GetConfig takes the assorted inputs and merges them into goschtalt.Config objet.

• name is the application name.
• prefix is the environment variable prefix to search for.
• cfg is the default configuration text and extension.
• opts are any options you would like to customize.

Notes:

• The caller must ensure there is a decoder available for the config data passed in. For example, if the config data is yaml format, make sure there is a yaml decoder specified.
• A fully documented (with comments describing the configuration file options) config file is a great way to provide documentation to your users.
• If a nil configuration is returned, that means the program should exit. The error value indicates if an error occurred or a graceful exit should happen.