Flag: Toggle Group

Togglable Group

Treat a group of flags as a radio button group in GUI, so the last flags will be reset while the flag in same group is been parsed ok and set.

Generally, both these flags should have a boolean default value. And only one flag have true value. If the rule is not obeyed, cmdr keeps the last one (true value of the flags).

Define

.ToggleGroup(toggleGroupName) can do that.

toggleGroupName makes the flags into a same toggle group. It is also used as the group name.

In phase invoking OnAction, the final value of the toggale group can be read by cmd.Store().MustBool(toggleGroupName).

Since v2.1.16, Multiple Selections for a Toggle Group is avaliable: the final selected items can be read by cmd.Store().MustStringSlice(toggleGroupName+".selected").

A sample here,

package main

import (
	"context"
	"os"

	"github.com/hedzr/cmdr/v2"
	"github.com/hedzr/cmdr/v2/cli"
	"github.com/hedzr/cmdr/v2/examples/common"
	logz "github.com/hedzr/logg/slog"
)

const (
	appName = "toggle-group"
	desc    = `a sample to show u what looking of a toggleable-group option in the help screen.`
	version = cmdr.Version
	author  = `The Example Authors`
)

func main() {
	app := cmdr.Create(appName, version, author, desc).
		With(func(app cli.App) {}).
		WithBuilders(common.AddToggleGroupCommand).
		WithAdders().
		Build()

	ctx := context.Background()
	if err := app.Run(ctx); err != nil {
		logz.ErrorContext(ctx, "Application Error:", "err", err) // stacktrace if in debug mode/build
		os.Exit(app.SuggestRetCode())
	} else if rc := app.SuggestRetCode(); rc != 0 {
		os.Exit(rc)
	}
}

package examples

import (
	"context"
	"fmt"

	"github.com/hedzr/cmdr/v2/cli"
)

// AddToggleGroupCommand _
//
// Sample code,
//
//	app.RootBuilder(common.AddToggleGroupCommand)
//
// Or,
//
//	app := cmdr.Create(appName, version, author, desc).
//		WithBuilders(common.AddToggleGroupCommand).
//		Build()
//	app.Run(context.TODO())
// [!code fold:59]
func AddToggleGroupCommand(parent cli.CommandBuilder) { //nolint:revive
	// toggle-group-test - without a default choice

	parent.Cmd("tg-test", "tg").
		Description("toggable group, with a default choice", "tg test new features,\nverbose long descriptions here.").
		Group("Toggleable Group").
		OnAction(func(ctx context.Context, cmd cli.Cmd, args []string) (err error) {
			fmt.Printf("*** Got fruit (toggle group): %q\n", cmd.Store().MustString(toggleGroupName))
			fmt.Printf("         multiple selections: %q\n", cmd.Store().MustStringSlice(toggleGroupName+".selected"))

			println()
			// fmt.Printf("> STDIN MODE: %v \n", cmd.Set().MustBool("mx-test.stdin"))
			// fmt.Println()
			return
		}).
		With(func(cb cli.CommandBuilder) {
			cb.Flg("apple", "").
				Default(false).
				Description("the test text.", "").
				ToggleGroup(toggleGroupName).
				Build()
			cb.Flg("banana", "").
				Default(false).
				Description("the test text.", "").
				ToggleGroup(toggleGroupName).
				Build()
			cb.Flg("orange", "").
				Default(true).
				Description("the test text.", "").
				ToggleGroup(toggleGroupName).
				Build()
		})

	// tg2 - with a default choice

	parent.Cmd("tg-test2", "tg2", "toggle-group-test2").
		Description("toggable group 2, without default choice", "tg2 test new features,\nverbose long descriptions here.").
		Group("Toggleable Group").
		OnAction(func(ctx context.Context, cmd cli.Cmd, args []string) (err error) {
			fmt.Printf("*** Got fruit (toggle group): %q\n", cmd.Store().MustString(toggleGroupName))
			fmt.Printf("         multiple selections: %q\n", cmd.Store().MustStringSlice(toggleGroupName+".selected"))

			println()
			// fmt.Printf("> STDIN MODE: %v \n", cmd.Set().MustBool("mx-test.stdin"))
			// fmt.Println()
			return
		}).
		With(func(cb cli.CommandBuilder) {
			cb.Flg("apple", "a").
				Default(true).
				Description("the test text.", "").
				ToggleGroup(toggleGroupName).
				Build()
			cb.Flg("banana", "b").
				Default(false).
				Description("the test text.", "").
				ToggleGroup(toggleGroupName).
				Build()
			cb.Flg("orange", "o").
				Default(false).
				Description("the test text.", "").
				ToggleGroup(toggleGroupName).
				Build()
		})
}

func AddToggleGroupFlags(c cli.CommandBuilder) { //nolint:revive
	c.Flg("apple", "a").
		Default(false).
		Description("the test text.", "").
		ToggleGroup(toggleGroupName).
		Group("Toggleable Group").
		Build()

	c.Flg("banana", "b").
		Default(false).
		Description("the test text.", "").
		ToggleGroup(toggleGroupName).
		Group("Toggleable Group").
		Build()

	c.Flg("orange", "o").
		Default(true).
		Description("the test text.", "").
		ToggleGroup(toggleGroupName).
		Group("Toggleable Group").
		Build()
}

const toggleGroupName = "fruit"

Run

In the help screen, the flags in a toggle group will be shown with a leading checkbox, just like the following output:

$ go run ./examples/toggle-group tg2 --help
toggle-group v2.1.16 ~ Copyright © 2025 by The Example Authors ~ All Rights Reserved.

Usage:

  $ toggle-group tg-test2 [Options...][files...]

Description:

  tg2 test new features,
  verbose long descriptions here.

Flags:
  [fruit]
    -a, --apple                               [x] the test text. (Default: true)
    -b, --banana                              [ ] the test text. (Default: false)
    -o, --orange                              [ ] the test text. (Default: false)

Global Flags:
  [Misc]
    -h, --help,--info,--usage                 Show this help screen (-?) [Env: HELP] (Default: true)

Type '-h'/'-?' or '--help' to get command help screen.
More: '-D'/'--debug', '-V'/'--version', '-#'/'--build-info', '--no-color'...

$ go run ./examples/toggle-group tg2 --banana --orange
*** Got fruit (toggle group): "orange"
         multiple selections: ["banana" "orange"]

$ go run ./examples/toggle-group tg2 --banana
*** Got fruit (toggle group): "banana"
         multiple selections: ["banana"]

$

And the final value banana will be retrieved properly.

额外的话题

Required

Toggle Group

Valid Args

Head Like

External Tool

Plus Sign

Event Handlers

What is Next?

Togglable Group

Treat a group of flags as a radio button group in GUI, so the last flags will be reset while the flag in same group is been parsed ok and set.

Generally, both these flags should have a boolean default value. And only one flag have true value. If the rule is not obeyed, cmdr keeps the last one (true value of the flags).

Define

.ToggleGroup(toggleGroupName) can do that.

toggleGroupName makes the flags into a same toggle group. It is also used as the group name.

In phase invoking OnAction, the final value of the toggale group can be read by cmd.Store().MustBool(toggleGroupName).

Since v2.1.16, Multiple Selections for a Toggle Group is avaliable: the final selected items can be read by cmd.Store().MustStringSlice(toggleGroupName+".selected").

A sample here,

package main

import (
	"context"
	"os"

	"github.com/hedzr/cmdr/v2"
	"github.com/hedzr/cmdr/v2/cli"
	"github.com/hedzr/cmdr/v2/examples/common"
	logz "github.com/hedzr/logg/slog"
)

const (
	appName = "toggle-group"
	desc    = `a sample to show u what looking of a toggleable-group option in the help screen.`
	version = cmdr.Version
	author  = `The Example Authors`
)

func main() {
	app := cmdr.Create(appName, version, author, desc).
		With(func(app cli.App) {}).
		WithBuilders(common.AddToggleGroupCommand).
		WithAdders().
		Build()

	ctx := context.Background()
	if err := app.Run(ctx); err != nil {
		logz.ErrorContext(ctx, "Application Error:", "err", err) // stacktrace if in debug mode/build
		os.Exit(app.SuggestRetCode())
	} else if rc := app.SuggestRetCode(); rc != 0 {
		os.Exit(rc)
	}
}

package examples

import (
	"context"
	"fmt"

	"github.com/hedzr/cmdr/v2/cli"
)

// AddToggleGroupCommand _
//
// Sample code,
//
//	app.RootBuilder(common.AddToggleGroupCommand)
//
// Or,
//
//	app := cmdr.Create(appName, version, author, desc).
//		WithBuilders(common.AddToggleGroupCommand).
//		Build()
//	app.Run(context.TODO())
// [!code fold:59]
func AddToggleGroupCommand(parent cli.CommandBuilder) { //nolint:revive
	// toggle-group-test - without a default choice

	parent.Cmd("tg-test", "tg").
		Description("toggable group, with a default choice", "tg test new features,\nverbose long descriptions here.").
		Group("Toggleable Group").
		OnAction(func(ctx context.Context, cmd cli.Cmd, args []string) (err error) {
			fmt.Printf("*** Got fruit (toggle group): %q\n", cmd.Store().MustString(toggleGroupName))
			fmt.Printf("         multiple selections: %q\n", cmd.Store().MustStringSlice(toggleGroupName+".selected"))

			println()
			// fmt.Printf("> STDIN MODE: %v \n", cmd.Set().MustBool("mx-test.stdin"))
			// fmt.Println()
			return
		}).
		With(func(cb cli.CommandBuilder) {
			cb.Flg("apple", "").
				Default(false).
				Description("the test text.", "").
				ToggleGroup(toggleGroupName).
				Build()
			cb.Flg("banana", "").
				Default(false).
				Description("the test text.", "").
				ToggleGroup(toggleGroupName).
				Build()
			cb.Flg("orange", "").
				Default(true).
				Description("the test text.", "").
				ToggleGroup(toggleGroupName).
				Build()
		})

	// tg2 - with a default choice

	parent.Cmd("tg-test2", "tg2", "toggle-group-test2").
		Description("toggable group 2, without default choice", "tg2 test new features,\nverbose long descriptions here.").
		Group("Toggleable Group").
		OnAction(func(ctx context.Context, cmd cli.Cmd, args []string) (err error) {
			fmt.Printf("*** Got fruit (toggle group): %q\n", cmd.Store().MustString(toggleGroupName))
			fmt.Printf("         multiple selections: %q\n", cmd.Store().MustStringSlice(toggleGroupName+".selected"))

			println()
			// fmt.Printf("> STDIN MODE: %v \n", cmd.Set().MustBool("mx-test.stdin"))
			// fmt.Println()
			return
		}).
		With(func(cb cli.CommandBuilder) {
			cb.Flg("apple", "a").
				Default(true).
				Description("the test text.", "").
				ToggleGroup(toggleGroupName).
				Build()
			cb.Flg("banana", "b").
				Default(false).
				Description("the test text.", "").
				ToggleGroup(toggleGroupName).
				Build()
			cb.Flg("orange", "o").
				Default(false).
				Description("the test text.", "").
				ToggleGroup(toggleGroupName).
				Build()
		})
}

func AddToggleGroupFlags(c cli.CommandBuilder) { //nolint:revive
	c.Flg("apple", "a").
		Default(false).
		Description("the test text.", "").
		ToggleGroup(toggleGroupName).
		Group("Toggleable Group").
		Build()

	c.Flg("banana", "b").
		Default(false).
		Description("the test text.", "").
		ToggleGroup(toggleGroupName).
		Group("Toggleable Group").
		Build()

	c.Flg("orange", "o").
		Default(true).
		Description("the test text.", "").
		ToggleGroup(toggleGroupName).
		Group("Toggleable Group").
		Build()
}

const toggleGroupName = "fruit"

Run

In the help screen, the flags in a toggle group will be shown with a leading checkbox, just like the following output:

$ go run ./examples/toggle-group tg2 --help
toggle-group v2.1.16 ~ Copyright © 2025 by The Example Authors ~ All Rights Reserved.

Usage:

  $ toggle-group tg-test2 [Options...][files...]

Description:

  tg2 test new features,
  verbose long descriptions here.

Flags:
  [fruit]
    -a, --apple                               [x] the test text. (Default: true)
    -b, --banana                              [ ] the test text. (Default: false)
    -o, --orange                              [ ] the test text. (Default: false)

Global Flags:
  [Misc]
    -h, --help,--info,--usage                 Show this help screen (-?) [Env: HELP] (Default: true)

Type '-h'/'-?' or '--help' to get command help screen.
More: '-D'/'--debug', '-V'/'--version', '-#'/'--build-info', '--no-color'...

$ go run ./examples/toggle-group tg2 --banana --orange
*** Got fruit (toggle group): "orange"
         multiple selections: ["banana" "orange"]

$ go run ./examples/toggle-group tg2 --banana
*** Got fruit (toggle group): "banana"
         multiple selections: ["banana"]

$

And the final value banana will be retrieved properly.

Flag: Toggle Group

Togglable Group

Define

Run

额外的话题

Required

Toggle Group

Valid Args

Head Like

External Tool

Plus Sign

Event Handlers

What is Next?

On this page

Flag: Toggle Group

Togglable Group

Define

Run

额外的话题

Required

Toggle Group

Valid Args

Head Like

External Tool

Plus Sign

Event Handlers

What is Next?

On this page