How to read resolved values after Run
To read resolved values in main after Run returns, pass your own root struct to conga.New. This guide uses a one-flag greet program.
Pass your own instance to conga.New
Section titled “Pass your own instance to conga.New”Allocate the root struct and pass its pointer. CONGA resolves every value into that instance, and session.Root[CLI]() returns the same pointer inside lifecycle methods:
type CLI struct { Name conga.OptionalFlag[string] `default:"World" help:"Name to greet"`}
func (c *CLI) Run(ctx context.Context, session *conga.Session) error { fmt.Fprintf(session.Stdout(), "Hello, %s!\n", c.Name.Get())
return nil}
func main() { cli := &CLI{} app := conga.New(cli). Name("greet"). EnvPrefix("GREET")
if err := app.Run(); err != nil { app.Exit(err) }
fmt.Fprintf(os.Stderr, "name=%q source=%s detail=%q changed=%t\n", cli.Name.Get(), cli.Name.Source(), cli.Name.SourceDetail(), cli.Name.Changed())}$ greet --name AliceHello, Alice!name="Alice" source=cli detail="--name" changed=trueRead where each value came from
Section titled “Read where each value came from”After Run, each container holds its value and the source that set it. Source returns a conga.ValueSource, SourceDetail names the flag, variable, file, or default it came from, and Changed reports whether the value came from the command line, an environment variable, or a config file:
$ greetHello, World!name="World" source=default detail="World" changed=false$ GREET_NAME=Bob greetHello, Bob!name="Bob" source=env detail="GREET_NAME" changed=trueContainers lists every reader method, and About value precedence explains which source wins.
Handle --help and --version runs
Section titled “Handle --help and --version runs”--help and --version print their output and return nil from Run without resolving any value, so the code after Run sees every container unset:
$ greet --helpUsage: greet [flags]
Flags: --name="World" Name to greet [env: GREET_NAME] --help Show help --version Show versionname="" source=none detail="" changed=falseCheck IsSet(), or compare Source() with conga.SourceNone, before acting on a value after Run. On a usage error, app.Exit ends the process before that code runs.
Know what goes wrong
Section titled “Know what goes wrong”| Mistake | When | Result |
|---|---|---|
conga.New receives a nil pointer |
Startup | Panic: conga: New requires a non-nil root instance |
Run or RunContext is called a second time on one App |
Second call | Panic: conga: App already executed |
The code after Run reads values on a --help or --version run |
After Run |
Zero values with source none |
The instance passed to conga.New is never used outside the app |
conga-lint |
conga.New root instance is not referenced outside the app (use conga.New[CLI]() to let the engine allocate the root) |
The last row is only a lint finding, and the program still runs normally. When nothing outside the app reads the root, use conga.New[CLI]().
Where to go next
Section titled “Where to go next”- Containers:
Get,GetOr,IsSet,Changed,Source, andSourceDetailfor every container. - How to test a command: run a fresh
Appper test case and assert on the resolved values. - About value precedence: how CONGA picks the winning source for each value.