greenery

Example_custom is an example application showing how to enable greenery to parse custom configuration variables.

package main

import (
	"fmt"
	"io/ioutil"
	"os"
	"strings"

	"github.com/woodensquares/greenery"
)

type exampleCustomNameValue struct {
	Name  string
	Value string
}

type exampleCSVStruct struct {
	First  string
	Second string
	Third  string
}

type exampleCustomConfig struct {
	*greenery.BaseConfig
	NameValue []exampleCustomNameValue `greenery:"||custom,           custom-app.namevalue,"`
	CSV       exampleCSVStruct         `greenery:"||custom,           custom-app.csv,"`
	List      []string                 `greenery:"||custom,           custom-app.csv,"`
}

func exampleNewCustomConfig() *exampleCustomConfig {
	cfg := &exampleCustomConfig{
		BaseConfig: greenery.NewBaseConfig("custom", map[string]greenery.Handler{
			"display": exampleCustomDisplay,
		}),
		NameValue: []exampleCustomNameValue{},
		CSV:       exampleCSVStruct{},
		List:      []string{},
	}

	cfg.RegisterExtraParse(exampleCustomParse, []string{
		"custom-app.namevalue",
		"custom-app.csv",
		"custom-app.list",
	})

	return cfg
}

var exampleCustomDocs = map[string]*greenery.DocSet{
	"en": &greenery.DocSet{
		Short: "URL fetcher",
		Usage: map[string]*greenery.CmdHelp{
			"display": &greenery.CmdHelp{
				Short: "Show some custom variables",
			},
		},
		ConfigFile: map[string]string{
			"NameValue": "a set of name/value pairs",
			"CSV":       "a comma separated value variable",
			"List":      "a list of strings",
		},
	},
}

func exampleCustomParse(lcfg greenery.Config, vals map[string]interface{}) ([]string, error) {
	cfg := lcfg.(*exampleCustomConfig)
	var processed []string

	for k, v := range vals {
		switch k {
		case "custom-app.namevalue":
			if err := lcfg.Unmarshal(k, &cfg.NameValue); err != nil {
				return nil, err
			}
			processed = append(processed, k)
		case "custom-app.list":
			if err := lcfg.Unmarshal(k, &cfg.List); err != nil {
				return nil, err
			}
			processed = append(processed, k)
		case "custom-app.csv":
			vv, ok := v.(string)
			if !ok {
				return nil, fmt.Errorf("Unexpected type %T for key %s, not a string: %v", v, k, v)
			}

			parts := strings.Split(vv, ",")
			if len(parts) != 3 {
				return nil, fmt.Errorf("Invalid value for key %s: %v", k, v)
			}

			cfg.CSV.First = parts[0]
			cfg.CSV.Second = parts[1]
			cfg.CSV.Third = parts[2]

			processed = append(processed, k)
		}
	}

	return processed, nil
}

func exampleCustomDisplay(lcfg greenery.Config, args []string) error {
	cfg := lcfg.(*exampleCustomConfig)
	fmt.Printf("NameValue is %v\n", cfg.NameValue)
	fmt.Printf("CSV is %v\n", cfg.CSV)
	fmt.Printf("List is %v\n", cfg.List)
	return nil
}

func exampleCustomMain() {
	cfg := exampleNewCustomConfig()
	defer cfg.Cleanup()

	if err := cfg.Execute(cfg, exampleCustomDocs); err != nil {
		fmt.Fprintf(os.Stderr, "Error executing: %s\n", err)
		os.Exit(1)
	}
}

// Example_custom is an example application showing how to enable greenery to
// parse custom configuration variables.
func main() {
	fmt.Println("----------------------------------------------------------")
	cfgFile, err := ioutil.TempFile("", "custom")
	if err != nil {
		fmt.Println("Cannot create a temporary file")
		os.Exit(1)
	}
	defer func() {
		_ = os.Remove(cfgFile.Name())
	}()

	if _, err = cfgFile.Write([]byte(`# Sample config file
[custom-app]
csv = "first,second,third"
list = [ "10.0.0.1", "10.0.0.2", "10.0.0.3" ]

[[custom-app.namevalue]]
name = "k1"
value = "v1"
[[custom-app.namevalue]]
name = "k2"
value = "v2"
`)); err != nil {
		fmt.Println("Cannot write the config file")
		os.Exit(1)
	}
	if err := cfgFile.Close(); err != nil {
		fmt.Println("Cannot close the config file")
		os.Exit(1)
	}

	os.Args = []string{"custom", "-c", cfgFile.Name(), "display"}
	fmt.Printf("Displaying some custom values set in the config file\n\n")
	exampleCustomMain()

}

Output:

----------------------------------------------------------
Displaying some custom values set in the config file

NameValue is [{k1 v1} {k2 v2}]
CSV is {first second third}
List is [10.0.0.1 10.0.0.2 10.0.0.3]

Example_localized is just like Example_minimal, but supporting a fully localized additional language, pig latin, if called with LANG set to zz.ZZZ. A sample invocation of the help message setting the LANG environment variable to two different values is provided.

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/woodensquares/greenery"
)

type exampleLocalizedConfig struct {
	*greenery.BaseConfig
	Timeout *greenery.IntValue `greenery:"get|timeout|t,      localized-app.timeout,   TIMEOUT"`
}

func exampleNewLocalizedConfig() *exampleLocalizedConfig {
	cfg := &exampleLocalizedConfig{
		BaseConfig: greenery.NewBaseConfig("localized", map[string]greenery.Handler{
			"get<": exampleLocalizedGetter,
		}),
		Timeout: greenery.NewIntValue("Timeout", 0, 1000),
	}

	if err := cfg.Timeout.SetInt(400); err != nil {
		panic("Could not initialize the timeout to its default")
	}

	return cfg
}

// Sample localization in pig latin, using the []strings format for
// compactness and ease of editing even for non-golang developers
var exampleLocalizedPiglatin = []string{
	"1.0",
	greenery.DocBaseDelimiter,
	// Root command values
	greenery.DocShort,
	"RLUay etcherfay",
	greenery.DocLong,
	"RLUay etcherfay ongerlay escriptionday",
	greenery.DocExample,
	"    Eesay ethay etgay ommandcay orfay examplesay",
	greenery.DocHelpFlag,
	"Elphay informationay orfay ethay applicationay.",
	greenery.DocCmdFlags,
	"[lagsfay]",
	greenery.DocConfigEnvMsg1,
	`Ethay ollowingfay environmentay ariablesvay areay activeay anday ouldcay affectay ethay executionay
ofay ethay ogrampray ependingday onay ommandcay inelay argumentsay:`,
	greenery.DocConfigEnvMsg2,
	"Onay ariablesvay",
	greenery.DocConfigEnvMsg3,
	"Ethay ollowingfay environmentay ariablesvay areay availableay orfay isthay ogrampray:",
	greenery.DocBaseDelimiter,

	// General help template strings
	greenery.DocHelpDelimiter,
	greenery.DocUsage,
	"Sageuay:",
	greenery.DocAliases,
	"Liasesaay:",
	greenery.DocExamples,
	"Ampleseay:",
	greenery.DocAvailableCommands,
	"Vailableaay Ommandscay:",
	greenery.DocFlags,
	"Lagsfay:",
	greenery.DocGlobalFlags,
	"Lobalgay Lagsfay:",
	greenery.DocAdditionalHelpTopics,
	"Dditionalaay elphay opicstay:",
	greenery.DocProvidesMoreInformationAboutACommand,
	"povidespay oremay informationay aboutay aay ommandcay.",
	greenery.DocHelpDelimiter,

	// Individual command usage strings, system first
	greenery.DocUsageDelimiter,
	greenery.DocHelpCmd,
	"[ommandcay]",
	"Elphay aboutay anyay command",
	`Elphay ovidesrpay helpay orfay anyay ommandcay inay ethay applicationay.
Implysay ypetay appnameay elphay [path otay ommandcay] orfay ullfay etailsday.`,
	"",
	greenery.DocConfigCmd,
	"",
	"Onfigurationcay ilefay elatedray ommandscay",
	"",
	"",
	greenery.DocConfigInitCmd,
	"",
	"Reatescay aay efaultday onfigcay ilefay inay wdcay oray hereway -c isay etsay",
	`Enwhay histay ommandcay isay executeday aay onfigurationcay ilefay illway ebay reatedcay
"inay hetay pecifiedsay ocationlay (in hetay urrentcay irectoryday ybay default", oray overnedgay
"ybay hetay aluevay assedpay otay hetay wdcay flag). Histay onfigurationcay ilefay illway ontaincay
"allay hetay upportedsay ariablesvay ithway heirtay efaultday values`,
	"",
	greenery.DocConfigEnvCmd,
	"",
	"Howssay hetay activeay environmentay ariablesvay hattay ouldway impactay hetay program",
	"",
	"",
	greenery.DocConfigDisplayCmd,
	"",
	"Howssay hetay urrentcay onfigurationcay values",
	`Howsay hetay urrentcay onfigurationcay aluesvay akingtay intoay accountay allay environmentay
"anday onfigurationcay ilefay values. Command-line agsflay invaliday orfay hetay onfigcay isplayday
"ommandcay ouldway otnay ebay displayed`,
	"",
	greenery.DocVersionCmd,
	"",
	"Rintspay outay hetay ersionvay umbernay ofay hetay ogramrpay",
	"",
	"",

	// Our command
	"get",
	"[UEI otay fetch]",
	"Etrievesray hetay pecifiedsay agepay",
	"",
	`    Otay etrieveray a agepay availableay onay localhost atay /hello.html implysay unray

    localized get http://localhost/hello.html`,
	greenery.DocUsageDelimiter,

	// Cmdline variable descriptions, system first
	greenery.DocCmdlineDelimiter,
	greenery.DocLogLevel,
	"Hetay oglay evellay ofay hetay ogrampray. Alidvay aluesvay areay \"error\", \"warn\", \"info\" anday \"debug\"",
	greenery.DocConfFile,
	"Hetay onfigurationcay ilefay ocationlay",
	greenery.DocLogFile,
	"Hetay oglay ilefay ocationlay",
	greenery.DocPretty,
	"Fiay etsay hetay onsolecay outputay ofay hetay ogginglay allscay illway ebay ettifiedpray",
	greenery.DocNoCfg,
	"Fiay etsay onay onfigurationay ilefay illway ebay oadedlay",
	greenery.DocNoEnv,
	"Fiay etsay hetay environmentay ariablesvay illway otnay ebay onsideredcay",
	greenery.DocVerbosity,
	"Hetay erbosityvay ofay hetay ogrampray, anay integeray etweenbay 0 anday 3 inclusiveay.",
	greenery.DocDoTrace,
	"Enablesay acingtray",
	greenery.DocCfgLocation,
	"Hereway otay itewray hetay onfigurationcay ilefay, oneay ofay \"cwd\", \"user\" oray \"system\"",
	greenery.DocCfgForce,
	"Fiay specified, anyay existingay onfigurationcay ilesfay illway ebay overwrittenay",
	// our flag
	"Timeout",
	"Hetay imeouttay otay useay orfay hetay ETGay operationay",
	greenery.DocCmdlineDelimiter,

	// Config file variable descriptions (where different from the cmdline)
	greenery.DocConfigDelimiter,
	greenery.DocConfigHeader,
	"Onfigurationcay eneratedgay onay {{ date }}",
	greenery.DocConfigDelimiter,

	// Custom message
	greenery.DocCustomDelimiter,
	"Message",
	"Illway etchfay %s ithway imeouttay %d illisecondsmay\n",
	greenery.DocCustomDelimiter,
}

// Same in English, this will of course contain only values specific to our
// application.
var exampleLocalizedEnglish = []string{
	"1.0",
	greenery.DocBaseDelimiter,

	// Root command
	greenery.DocShort,
	"URL fetcher",
	greenery.DocExample,
	"    See the get command for examples",
	greenery.DocBaseDelimiter,

	// Additional commands, get in this case
	greenery.DocUsageDelimiter,
	"get",
	"[URI to fetch]",
	"Retrieves the specified page",
	"",
	`    To retrieve a page available on localhost at /hello.html simply run

    localized get http://localhost/hello.html`,
	greenery.DocUsageDelimiter,

	// Cmdline flag documentation
	greenery.DocCmdlineDelimiter,
	"Timeout",
	"the timeout, in milliseconds, to use for the fetch",
	greenery.DocCmdlineDelimiter,

	// Custom message
	greenery.DocCustomDelimiter,
	"Message",
	"Will fetch %s with timeout %d milliseconds\n",
	greenery.DocCustomDelimiter,
}

var exampleLocalizedDocs = greenery.ConvertOrPanic(map[string][]string{
	"en":     exampleLocalizedEnglish,
	"zz.ZZZ": exampleLocalizedPiglatin,
})

func exampleLocalizedGetter(lcfg greenery.Config, args []string) error {
	cfg := lcfg.(*exampleLocalizedConfig)

	if len(args) != 1 {
		return fmt.Errorf("Invalid number of command line arguments")
	}

	cfg.Debugf("fetching %s, timeout %d", args[0], cfg.Timeout.Value)
	_, docs := cfg.GetDocs()
	fmt.Printf(docs.Custom["Message"], args[0], cfg.Timeout.Value)
	return nil
}

func exampleLocalizedMain() {
	cfg := exampleNewLocalizedConfig()
	defer cfg.Cleanup()

	cfg.VersionMajor = "1"
	cfg.VersionMinor = "0"

	if err := cfg.Execute(cfg, exampleLocalizedDocs); err != nil {
		fmt.Fprintf(os.Stderr, "Error executing: %s\n", err)
		os.Exit(1)
	}
}

// Example_localized is just like Example_minimal, but supporting a fully
// localized additional language, pig latin, if called with LANG set to
// zz.ZZZ. A sample invocation of the help message setting the LANG
// environment variable to two different values is provided.
func main() {
	fmt.Println("----------------------------------------------------------")
	if err := os.Setenv("LANG", "en_US.UTF-8"); err != nil {
		log.Fatal(err.Error())
	}

	fmt.Printf("Default help for the get command\n\n")
	os.Args = []string{"localized", "get", "-h"}
	exampleLocalizedMain()

	fmt.Printf("Default command output\n\n")
	os.Args = []string{"localized", "get", "http://127.0.0.1"}
	exampleLocalizedMain()

	if err := os.Setenv("LANG", "zz.ZZZ"); err != nil {
		log.Fatal(err.Error())
	}
	fmt.Println("----------------------------------------------------------")
	fmt.Printf("\nLocalized help for the get command\n\n")
	os.Args = []string{"localized", "get", "-h"}
	exampleLocalizedMain()

	fmt.Printf("Localized command output\n\n")
	os.Args = []string{"localized", "get", "http://127.0.0.1"}
	exampleLocalizedMain()

}

Output:

----------------------------------------------------------
Default help for the get command

Retrieves the specified page

Usage:
  localized get [URI to fetch] [flags]

Examples:
    To retrieve a page available on localhost at /hello.html simply run

    localized get http://localhost/hello.html

Flags:
  -t, --timeout int   the timeout, in milliseconds, to use for the fetch (default 400)

Global Flags:
  -c, --config string      The configuration file location
      --help               help information for the application.
      --log-file string    The log file location
  -l, --log-level string   The log level of the program. Valid values are "error", "warn", "info" and "debug" (default "error")
      --no-cfg             If set no configuration file will be loaded
      --no-env             If set the environment variables will not be considered
      --pretty             If set the console output of the logging calls will be prettified
  -v, --verbosity int      The verbosity of the program, an integer between 0 and 3 inclusive. (default 1)

Default command output

Will fetch http://127.0.0.1 with timeout 400 milliseconds
----------------------------------------------------------

Localized help for the get command

Etrievesray hetay pecifiedsay agepay

Sageuay:
  localized get [UEI otay fetch] [lagsfay]

Ampleseay:
    Otay etrieveray a agepay availableay onay localhost atay /hello.html implysay unray

    localized get http://localhost/hello.html

Lagsfay:
  -t, --timeout int   Hetay imeouttay otay useay orfay hetay ETGay operationay (default 400)

Lobalgay Lagsfay:
  -c, --config string      Hetay onfigurationcay ilefay ocationlay
      --help               Elphay informationay orfay ethay applicationay.
      --log-file string    Hetay oglay ilefay ocationlay
  -l, --log-level string   Hetay oglay evellay ofay hetay ogrampray. Alidvay aluesvay areay "error", "warn", "info" anday "debug" (default "error")
      --no-cfg             Fiay etsay onay onfigurationay ilefay illway ebay oadedlay
      --no-env             Fiay etsay hetay environmentay ariablesvay illway otnay ebay onsideredcay
      --pretty             Fiay etsay hetay onsolecay outputay ofay hetay ogginglay allscay illway ebay ettifiedpray
  -v, --verbosity int      Hetay erbosityvay ofay hetay ogrampray, anay integeray etweenbay 0 anday 3 inclusiveay. (default 1)

Localized command output

Illway etchfay http://127.0.0.1 ithway imeouttay 400 illisecondsmay

Example_minimal shows a minimal application using the greery library. Invocations mimicking actual command-line usage setting the parameter value in different ways are provided for reference.

package main

import (
	"fmt"
	"io/ioutil"
	"os"

	"github.com/woodensquares/greenery"
)

type exampleMinimalConfig struct {
	*greenery.BaseConfig
	Timeout *greenery.IntValue `greenery:"get|timeout|t,      minimal-app.timeout,   TIMEOUT"`
}

func exampleNewMinimalConfig() *exampleMinimalConfig {
	cfg := &exampleMinimalConfig{
		BaseConfig: greenery.NewBaseConfig("minimal", map[string]greenery.Handler{
			"get<": exampleMinimalGetter,
		}),
		Timeout: greenery.NewIntValue("Timeout", 0, 1000),
	}

	if err := cfg.Timeout.SetInt(400); err != nil {
		panic("Could not initialize the timeout to its default")
	}

	return cfg
}

var exampleMinimalDocs = map[string]*greenery.DocSet{
	"en": &greenery.DocSet{
		Short: "URL fetcher",
		Usage: map[string]*greenery.CmdHelp{
			"get": &greenery.CmdHelp{
				Use:   "[URI to fetch]",
				Short: "Retrieves the specified page",
			},
		},
		CmdLine: map[string]string{
			"Timeout": "the timeout to use for the fetch",
		},
	},
}

func exampleMinimalGetter(lcfg greenery.Config, args []string) error {
	cfg := lcfg.(*exampleMinimalConfig)

	if len(args) != 1 {
		return fmt.Errorf("Invalid number of command line arguments")
	}

	cfg.Debugf("fetching %s, timeout %d", args[0], cfg.Timeout.Value)
	fmt.Printf("Will fetch %s with timeout %d milliseconds\n\n", args[0], cfg.Timeout.Value)
	return nil
}

func exampleMinimalMain() {
	cfg := exampleNewMinimalConfig()
	defer cfg.Cleanup()

	if err := cfg.Execute(cfg, exampleMinimalDocs); err != nil {
		fmt.Fprintf(os.Stderr, "Error executing: %s\n", err)
		os.Exit(1)
	}
}

// Example_minimal shows a minimal application using the greery
// library. Invocations mimicking actual command-line usage setting the
// parameter value in different ways are provided for reference.
func main() {
	fmt.Println("----------------------------------------------------------")

	// Execute with no arguments, will use the default timeout
	os.Args = []string{"minimal", "get", "http://127.0.0.1"}
	fmt.Println("Executing with the default timeout")
	exampleMinimalMain()

	// Execute with a commandline timeout argument
	os.Args = []string{"minimal", "get", "-t", "300", "http://127.0.0.1"}
	fmt.Println("Executing with a commandline timeout")
	exampleMinimalMain()

	// Create a configuration file with a timeout value
	cfgFile, err := ioutil.TempFile("", "minimal")
	if err != nil {
		fmt.Println("Cannot create a temporary file")
		os.Exit(1)
	}
	defer func() {
		_ = os.Remove(cfgFile.Name())
	}()

	if _, err = cfgFile.Write([]byte(`# Sample config file
[minimal-app]
timeout = 550
`)); err != nil {
		fmt.Println("Cannot write the config file")
		os.Exit(1)
	}
	if err := cfgFile.Close(); err != nil {
		fmt.Println("Cannot close the config file")
		os.Exit(1)
	}

	// Execute with the created configuration file
	os.Args = []string{"minimal", "get", "-c", cfgFile.Name(), "http://127.0.0.1"}
	fmt.Println("Executing with a configuration file")
	exampleMinimalMain()

	// Execute with an environment variable argument, together with the
	// configuration file, note the environment variable will have precedence
	if err := os.Setenv("MINIMAL_TIMEOUT", "200"); err != nil {
		fmt.Println("Cannot set an environment variable")
		os.Exit(1)
	}

	os.Args = []string{"minimal", "get", "-c", cfgFile.Name(), "http://127.0.0.1"}
	fmt.Println("Executing with a configuration and environment variable timeout")
	exampleMinimalMain()

	// Executing with commandline, config and environment timeout argument,
	// the commandline will take precedence
	os.Args = []string{"minimal", "get", "-c", cfgFile.Name(), "-t", "300", "http://127.0.0.1"}
	fmt.Println("Executing with a commandline, configuration and environment timeout")
	exampleMinimalMain()

}

Output:

----------------------------------------------------------
Executing with the default timeout
Will fetch http://127.0.0.1 with timeout 400 milliseconds

Executing with a commandline timeout
Will fetch http://127.0.0.1 with timeout 300 milliseconds

Executing with a configuration file
Will fetch http://127.0.0.1 with timeout 550 milliseconds

Executing with a configuration and environment variable timeout
Will fetch http://127.0.0.1 with timeout 200 milliseconds

Executing with a commandline, configuration and environment timeout
Will fetch http://127.0.0.1 with timeout 300 milliseconds