ser1.net/clapenv

clapenv

★ Changelog ★ Issues ★

Provides 12-Factor environment variable configuration support to claptrap.

clapenv will read environment variables and set claptrap arguments and flags.

Usage

Set up the claptrap config and run clapenv.Load() either before or after parsing the user arguments. clapenv will not overwrite user arguments regardless of when it is run. See the caveats below for constraints.

The environment variable names are formatted with the main command name and the argument name; if the argument name has any non-alphanumeric characters, they are converted to _, and all characters are upper case.

module example.com/test
go 1.16
require ser1.net/claptrap/v4 v4.1.7
require ser1.net/clapenv

package main
import (
  "ser1.net/claptrap/v4"
  "ser1.net/clapenv"
  "os" 
  "fmt"
)
func main() {
  root := claptrap.Command("main", "Showing env vars")
  root.Add("posarg", "a positional argument")
  root.Add("--flag", 0, "a numerical flag")
  clapenv.Load()
  root.Parse(nil)
  fmt.Printf("posarg = %q\n", root.String("posarg"))
  fmt.Printf("flag = %d\n", root.Int("flag"))
}

$ MAIN_POSARG="hello" MAIN_FLAG=99 go run .
posarg = "hello"
flag = 99

Caveats and Limitations

• Load() is not idempotent.
• If clapenv.Load() is called before claptrap.Parse(), and there are non-variadic arguments, and arguments are provided on both the command line and in the environment, claptrap will throw an error. If the arguments are variadic, then both values will be used.
• If clapenv.Load() is called after claptrap.Parse(), then the arguments will be used (and any duplicate env vars will not).

A consequence of these two rules is that the behavior differs depending on whether Load() is called before or after Parse(). The downside calling Load() first are the possible errors by the user also providing arguments. The downside to calling it after is that the user must supply mandatory arguments (because Parse() validates the inputs before Load() has a chance to work).

Like clapconf, clapenv can not set variadic values from environment variables. This is a deficiency that should be corrected.

This file is in Djot format; the suffix is .md merely to have Sourcehut pick it up and render it properly.