avamsi/climate

Climate

Climate "CLI Mate" aims to make creating CLIs in Go easy (and fun!), similar to python-fire.
It's also built on top of Cobra and so comes with "batteries included" (help, shell completion etc.).

Usage

climate/cmd/examples/greet/main.go

Lines 11 to 54 in 45ac608

    
           // Exported struct fields are automatically declared as flags -- 
        
           //	1. Field names are converted to kebab-case and are used as flag names. 
        
           //	   That said, users can pass flags in camelCase, PascalCase, snake_case or 
        
           //	   SCREAMING_SNAKE_CASE and everything just works (thanks to normalization). 
        
           //	2. Field types are used as flag types (string, bool, int, etc.). 
        
           //	3. "short" subfield tags (under the "cli" tags) are used as short flag names 
        
           //	   (as is). It's also possible to omit the value, in which case the first 
        
           //	   letter of the field name is used. 
        
           //	4. "default" field tags are used as default values (of course, with 
        
           //	   automatic type conversion from raw string to the actual field type). 
        
           //	5. Field docs / comments are used* as flag usage strings (as is). 
        
           //	6. "required" subfield tags (under the "cli" tags) are used to mark the 
        
           //	   flags as required (i.e., the command is errored out without these flags). 
        
           type greetOptions struct { 
        
           	Greeting string `cli:"short" default:"Hello"`   // greeting to use 
        
           	Name     string `cli:"short=n" default:"World"` // name to greet 
        
           	Times    int    `cli:"short,required"`          // number of times to greet 
        
           } 
        
           // Func is automatically converted to a command -- 
        
           //	1. Param names are converted to kebab-case and used* as part of the usage 
        
           //	   string ("command [opts] [args]", for example). 
        
           //	2. (Optional) First argument if a struct pointer, is used to declare flags. 
        
           //	3. (Optional) Next argument if a string slice is used to collect args. 
        
           //	4. Doc is used* as long help string (as is). 
        
           //	5. Usage directive is used* to explicitly set the usage string. 
        
           // Greet someone. 
        
           func greet(opts *greetOptions) { 
        
           	for i := 0; i < opts.Times; i++ { 
        
           		fmt.Printf("%v, %v!\n", opts.Greeting, opts.Name) 
        
           	} 
        
           } 
        
           // * These only work if you generate and pass along "metadata" like below -- 
        
           //go:generate go run github.com/avamsi/climate/cmd/cligen --out=md.cli 
        
           //go:embed md.cli 
        
           var md []byte 
        
           func main() { 
        
           	climate.RunAndExit(climate.Func(greet), climate.WithMetadata(md)) 
        
           }

$ greet --help

Greet someone.

Usage:
  greet [opts]

Flags:
  -g, --greeting string (default Hello)  greeting to use
  -n, --name     string (default World)  name to greet
  -t, --times    int                     number of times to greet
  -h, --help                             help for greet
  -v, --version                          version for greet

Subcommands

climate/cmd/examples/jj/main.go

Lines 14 to 87 in 45ac608

    
           // See ../greet/main.go first for some details that are not covered here. 
        
           // Struct is automatically converted to a command -- 
        
           //	1. Struct names are converted to lowercase and used as the command name. 
        
           //	2. Struct fields are automatically declared as "global" flags. 
        
           //	3. Struct methods are automatically converted to subcommands -- 
        
           //	   1. Method names are converted to lowercase and used as the command name. 
        
           //	   2. Method docs are truncated and are used* as short help strings. 
        
           //	   3. Method directives are used* to declare aliases or explicitly set the 
        
           //	      short help strings (//cli:aliases, for example). 
        
           //	4. "Sub-structs" are automatically converted to subcommands, recursively. 
        
           // Jujutsu (an experimental VCS). 
        
           type jj struct { 
        
           	Repository        string `cli:"short=R"` // `path` to the repo to operate on 
        
           	IgnoreWorkingCopy bool   // don't snapshot / update the working copy 
        
           } 
        
           // Create a new repo in the given directory. 
        
           func (j *jj) Init(ctx context.Context, dir *string) { 
        
           	fmt.Println("init", ctx, j, dir) 
        
           } 
        
           type squashOptions struct { 
        
           	Revision    string `cli:"short" default:"@"` 
        
           	Interactive bool   `cli:"short"` // interactively choose which parts to squash 
        
           } 
        
           // Move changes from a revision into its parent. 
        
           // 
        
           // After moving the changes into the parent, the child revision will have the 
        
           // same content state as before. If that means that the change is now empty 
        
           // compared to its parent, it will be abandoned. Without `--interactive`, the 
        
           // child change will always be empty. 
        
           // 
        
           //cli:aliases am, amend 
        
           func (j *jj) Squash(opts *squashOptions, paths [5]string) { 
        
           	fmt.Println("squash", j, opts, paths) 
        
           } 
        
           // Commands for working with the underlying Git repo. 
        
           type git struct { 
        
           	J *jj 
        
           } 
        
           // Manage Git remotes. 
        
           func (g *git) Remote() error { 
        
           	return errors.New("not implemented") 
        
           } 
        
           // Update the underlying Git repo with changes made in the repo. 
        
           func (g *git) Export() { 
        
           	fmt.Println("export", g.J) 
        
           } 
        
           //go:generate go run github.com/avamsi/climate/cmd/cligen --out=md.cli 
        
           //go:embed md.cli 
        
           var md []byte 
        
           func main() { 
        
           	// Note the recursive struct embedding below, which lets us create "deep" 
        
           	// subcommands like this (indentation implies subcommand) -- 
        
           	// 
        
           	// jj 
        
           	//     init 
        
           	//     squash 
        
           	//     git 
        
           	//         remote 
        
           	//         export 
        
           	//     util 
        
           	//         completion 
        
           	p := climate.Struct[jj](climate.Struct[git](), climate.Struct[util.Util]()) 
        
           	climate.RunAndExit(p, climate.WithMetadata(md)) 
        
           }

$ jj --help

Jujutsu (an experimental VCS).

Usage:
  jj [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  git         Commands for working with the underlying Git repo
  help        Help about any command
  init        Create a new repo in the given directory
  squash      Move changes from a revision into its parent
  util        Infrequently used commands such as for generating shell completions
  version     Display jj's version information

Flags:
  -R, --repository          path  path to the repo to operate on
      --ignore-working-copy       don't snapshot / update the working copy
  -h, --help                      help for jj
  -v, --version                   version for jj

Use "jj [command] --help" for more information about a command.

$ jj git --help

Commands for working with the underlying Git repo.

Usage:
  jj git [command]

Available Commands:
  export      Update the underlying Git repo with changes made in the repo
  remote      Manage Git remotes

Flags:
  -h, --help  help for git

Global Flags:
      --ignore-working-copy       don't snapshot / update the working copy
  -R, --repository          path  path to the repo to operate on

Use "jj git [command] --help" for more information about a command.

	// Exported struct fields are automatically declared as flags --
	// 1. Field names are converted to kebab-case and are used as flag names.
	// That said, users can pass flags in camelCase, PascalCase, snake_case or
	// SCREAMING_SNAKE_CASE and everything just works (thanks to normalization).
	// 2. Field types are used as flag types (string, bool, int, etc.).
	// 3. "short" subfield tags (under the "cli" tags) are used as short flag names
	// (as is). It's also possible to omit the value, in which case the first
	// letter of the field name is used.
	// 4. "default" field tags are used as default values (of course, with
	// automatic type conversion from raw string to the actual field type).
	// 5. Field docs / comments are used* as flag usage strings (as is).
	// 6. "required" subfield tags (under the "cli" tags) are used to mark the
	// flags as required (i.e., the command is errored out without these flags).

	type greetOptions struct {
	Greeting string `cli:"short" default:"Hello"` // greeting to use
	Name string `cli:"short=n" default:"World"` // name to greet
	Times int `cli:"short,required"` // number of times to greet
	}

	// Func is automatically converted to a command --
	// 1. Param names are converted to kebab-case and used* as part of the usage
	// string ("command [opts] [args]", for example).
	// 2. (Optional) First argument if a struct pointer, is used to declare flags.
	// 3. (Optional) Next argument if a string slice is used to collect args.
	// 4. Doc is used* as long help string (as is).
	// 5. Usage directive is used* to explicitly set the usage string.

	// Greet someone.
	func greet(opts *greetOptions) {
	for i := 0; i < opts.Times; i++ {
	fmt.Printf("%v, %v!\n", opts.Greeting, opts.Name)
	}
	}

	// * These only work if you generate and pass along "metadata" like below --

	//go:generate go run github.com/avamsi/climate/cmd/cligen --out=md.cli
	//go:embed md.cli
	var md []byte

	func main() {
	climate.RunAndExit(climate.Func(greet), climate.WithMetadata(md))
	}

	// See ../greet/main.go first for some details that are not covered here.

	// Struct is automatically converted to a command --
	// 1. Struct names are converted to lowercase and used as the command name.
	// 2. Struct fields are automatically declared as "global" flags.
	// 3. Struct methods are automatically converted to subcommands --
	// 1. Method names are converted to lowercase and used as the command name.
	// 2. Method docs are truncated and are used* as short help strings.
	// 3. Method directives are used* to declare aliases or explicitly set the
	// short help strings (//cli:aliases, for example).
	// 4. "Sub-structs" are automatically converted to subcommands, recursively.

	// Jujutsu (an experimental VCS).
	type jj struct {
	Repository string `cli:"short=R"` // `path` to the repo to operate on
	IgnoreWorkingCopy bool // don't snapshot / update the working copy
	}

	// Create a new repo in the given directory.
	func (j jj) Init(ctx context.Context, dir string) {
	fmt.Println("init", ctx, j, dir)
	}

	type squashOptions struct {
	Revision string `cli:"short" default:"@"`
	Interactive bool `cli:"short"` // interactively choose which parts to squash
	}

	// Move changes from a revision into its parent.
	//
	// After moving the changes into the parent, the child revision will have the
	// same content state as before. If that means that the change is now empty
	// compared to its parent, it will be abandoned. Without `--interactive`, the
	// child change will always be empty.
	//
	//cli:aliases am, amend
	func (j jj) Squash(opts squashOptions, paths [5]string) {
	fmt.Println("squash", j, opts, paths)
	}

	// Commands for working with the underlying Git repo.
	type git struct {
	J *jj
	}

	// Manage Git remotes.
	func (g *git) Remote() error {
	return errors.New("not implemented")
	}

	// Update the underlying Git repo with changes made in the repo.
	func (g *git) Export() {
	fmt.Println("export", g.J)
	}

	//go:generate go run github.com/avamsi/climate/cmd/cligen --out=md.cli
	//go:embed md.cli
	var md []byte

	func main() {
	// Note the recursive struct embedding below, which lets us create "deep"
	// subcommands like this (indentation implies subcommand) --
	//
	// jj
	// init
	// squash
	// git
	// remote
	// export
	// util
	// completion
	p := climate.Struct[jj](climate.Struct[git](), climate.Struct[util.Util]())
	climate.RunAndExit(p, climate.WithMetadata(md))
	}