From ef2b14552f93d9e1fe3b618627a1dcef80a61247 Mon Sep 17 00:00:00 2001 From: Gareth Jones Date: Sun, 27 Apr 2025 10:56:02 +1200 Subject: [PATCH 1/8] docs: add renames to v3 migration doc --- docs/migrate-v2-to-v3.md | 124 +++++++++++++++++++++++++++++++++------ 1 file changed, 106 insertions(+), 18 deletions(-) diff --git a/docs/migrate-v2-to-v3.md b/docs/migrate-v2-to-v3.md index 1b023ffcfd..ad2c566d17 100644 --- a/docs/migrate-v2-to-v3.md +++ b/docs/migrate-v2-to-v3.md @@ -23,6 +23,112 @@ Check each file for this and make the change. Shell command to find them all: `fgrep -rl github.com/urfave/cli/v2 *` +## New Names + +### cli.App + +=== "v2" + + ```go + cli.App{ + // ... + } + ``` + +=== "v3" + + ```go + cli.Command{ + // ... + } + ``` + +### cli.App.EnableBashCompletion + +=== "v2" + + ```go + cli.App{ + EnableBashCompletion: true, + } + ``` + +=== "v3" + + ```go + cli.Command{ + EnableShellCompletion: true, + } + ``` + +### cli.App.CustomAppHelpTemplate + +=== "v2" + + ```go + cli.App{ + CustomAppHelpTemplate: "...", + } + ``` + +=== "v3" + + ```go + cli.Command{ + CustomRootCommandHelpTemplate: "...", + } + ``` + +### cli.App.RunContext + +=== "v2" + + ```go + (&cli.App{}).RunContext(context.Background(), os.Args) + ``` + +=== "v3" + + ```go + (&cli.Command{}).Run(context.Background(), os.Args) + ``` + +### cli.App.BashComplete + +=== "v2" + + ```go + cli.App{ + BashComplete: func(ctx *cli.Context) {}, + } + ``` + +=== "v3" + + ```go + cli.Command{ + ShellComplete: func(ctx context.Context, cmd *cli.Command) {}, + } + ``` + +### cli.Command.Subcommands + +=== "v2" + + ```go + cli.Command{ + Subcommands: []*cli.Command{}, + } + ``` + +=== "v3" + + ```go + cli.Command{ + Commands: []*cli.Command{}, + } + ``` + ## Sources ### FilePath @@ -295,21 +401,3 @@ Similar messages would be shown for other funcs. }, } ``` - -## BashCompletion/ShellCompletion - -=== "v2" - - ```go - &cli.App{ - EnableBashCompletion: true, - } - ``` - -=== "v3" - - ```go - &cli.Command{ - EnableShellCompletion: true, - } - ``` From a1f65a0f654db5c9f5dffc394fb69b9b53b3545d Mon Sep 17 00:00:00 2001 From: Gareth Jones Date: Sun, 27 Apr 2025 11:32:45 +1200 Subject: [PATCH 2/8] docs: add `Float64` -> `Float` --- docs/migrate-v2-to-v3.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/migrate-v2-to-v3.md b/docs/migrate-v2-to-v3.md index ad2c566d17..31d71ca461 100644 --- a/docs/migrate-v2-to-v3.md +++ b/docs/migrate-v2-to-v3.md @@ -129,6 +129,40 @@ Shell command to find them all: `fgrep -rl github.com/urfave/cli/v2 *` } ``` +### cli.Float64Flag + +=== "v2" + + ```go + cli.Float64Flag{ + // ... + } + ``` + +=== "v3" + + ```go + cli.FloatFlag{ + // ... + } + ``` + +### cli.Context.Float64 + +=== "v2" + + ```go + // ctx is cli.Context + ctx.Float64("my-floating-flag") + ``` + +=== "v3" + + ```go + // cmd is cli.Command + cmd.Float("my-floating-flag") + ``` + ## Sources ### FilePath From a8fb70ed475d1e6df6dd12e35276e9fcf17bdec9 Mon Sep 17 00:00:00 2001 From: Gareth Jones Date: Mon, 28 Apr 2025 07:17:12 +1200 Subject: [PATCH 3/8] docs: remove section about `Float64` --- docs/migrate-v2-to-v3.md | 34 ---------------------------------- 1 file changed, 34 deletions(-) diff --git a/docs/migrate-v2-to-v3.md b/docs/migrate-v2-to-v3.md index 31d71ca461..ad2c566d17 100644 --- a/docs/migrate-v2-to-v3.md +++ b/docs/migrate-v2-to-v3.md @@ -129,40 +129,6 @@ Shell command to find them all: `fgrep -rl github.com/urfave/cli/v2 *` } ``` -### cli.Float64Flag - -=== "v2" - - ```go - cli.Float64Flag{ - // ... - } - ``` - -=== "v3" - - ```go - cli.FloatFlag{ - // ... - } - ``` - -### cli.Context.Float64 - -=== "v2" - - ```go - // ctx is cli.Context - ctx.Float64("my-floating-flag") - ``` - -=== "v3" - - ```go - // cmd is cli.Command - cmd.Float("my-floating-flag") - ``` - ## Sources ### FilePath From 6573da755802a4304840fd87198946f024243203 Mon Sep 17 00:00:00 2001 From: Naveen Gogineni Date: Sun, 27 Apr 2025 21:30:21 -0400 Subject: [PATCH 4/8] Add docs for advanced value source --- docs/v3/examples/flags/value-sources.md | 97 +++++++++++++------------ 1 file changed, 52 insertions(+), 45 deletions(-) diff --git a/docs/v3/examples/flags/value-sources.md b/docs/v3/examples/flags/value-sources.md index 49030922b4..283ad930f0 100644 --- a/docs/v3/examples/flags/value-sources.md +++ b/docs/v3/examples/flags/value-sources.md @@ -136,78 +136,85 @@ Note that default values are set in the same order as they are defined in the #### Values from alternate input sources (YAML, TOML, and others) -There is a separate package altsrc that adds support for getting flag values +There is a separate package [altsrc](https://github.com/urfave/cli-altsrc) that adds support for getting flag values from other file input sources. -Currently supported input source formats: +Currently supported input source formats by that library are: - YAML - JSON - TOML -In order to get values for a flag from an alternate input source the following -code would be added to wrap an existing cli.Flag like below: +A simple straight forward usage would be ```go - // --- >8 --- - altsrc.NewIntFlag(&cli.IntFlag{Name: "test"}) -``` +package main -Initialization must also occur for these flags. Below is an example initializing -getting data from a yaml file below. +import ( + "log" + "os" + "context" -```go - // --- >8 --- - command.Before = func(ctx context.Context, cmd *Command) (context.Context, error) { - return ctx, altsrc.InitInputSourceWithContext(command.Flags, NewYamlSourceFromFlagFunc("load")) - } -``` + "github.com/urfave/cli/v3" + "github.com/urfave/cli-altsrc/v3" +) -The code above will use the "load" string as a flag name to get the file name of -a yaml file from the cli.Context. It will then use that file name to initialize -the yaml input source for any flags that are defined on that command. As a note -the "load" flag used would also have to be defined on the command flags in order -for this code snippet to work. +func main() { + cmd := &cli.Command{ + Flags: []cli.Flag{ + &cli.StringFlag{ + Name: "password", + Aliases: []string{"p"}, + Usage: "password for the mysql database", + Sources: altsrc.YAML("somekey", altsrc.StringSourcer("/path/to/filename")), + }, + }, + } -Currently only YAML, JSON, and TOML files are supported but developers can add -support for other input sources by implementing the altsrc.InputSourceContext -for their given sources. + if err := cmd.Run(context.Background(), os.Args); err != nil { + log.Fatal(err) + } +} +``` -Here is a more complete sample of a command using YAML support: +Sometime the source name is itself provided by another CLI flag. To allow the library to "lazy-load" +the file when needed we use the `altsrc.NewStringPtrSourcer` function to bind the value of the flag +to a pointer that is set as a destination of another flag - ```go package main import ( - "context" - "fmt" + "log" "os" + "context" - altsrc "github.com/urfave/cli-altsrc/v3" "github.com/urfave/cli/v3" + "github.com/urfave/cli-altsrc/v3" ) func main() { - flags := []cli.Flag{ - &cli.IntFlag{ - Name: "test", - Sources: altsrc.YAML("key", "/path/to/file"), - }, - &cli.StringFlag{Name: "load"}, - } - + var filename string cmd := &cli.Command{ - Action: func(context.Context, *cli.Command) error { - fmt.Println("--test value.*default: 0") - return nil + Flags: []cli.Flag{ + &cli.StringFlag{ + Name: "file", + Aliases: []string{"f"}, + Value: "/path/to/default", + Usage: "filename for mysql database", + Destination: &filename, + }, + &cli.StringFlag{ + Name: "password", + Aliases: []string{"p"}, + Usage: "password for the mysql database", + Sources: altsrc.YAML("somekey", altsrc.NewStringPtrSourcer(&filename)), + }, }, - Flags: flags, } - cmd.Run(context.Background(), os.Args) + if err := cmd.Run(context.Background(), os.Args); err != nil { + log.Fatal(err) + } } -``` \ No newline at end of file +``` From b0e42aa5d12fba667fe84f3d4cfa0118d261428e Mon Sep 17 00:00:00 2001 From: Naveen Gogineni Date: Sun, 27 Apr 2025 21:42:24 -0400 Subject: [PATCH 5/8] Cleanup docs --- docs/v3/examples/arguments/advanced.md | 20 ++++++++++---------- docs/v3/examples/flags/basics.md | 2 +- docs/v3/examples/flags/value-sources.md | 4 +++- 3 files changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/v3/examples/arguments/advanced.md b/docs/v3/examples/arguments/advanced.md index 0d1dad3857..bfc96d4a8f 100644 --- a/docs/v3/examples/arguments/advanced.md +++ b/docs/v3/examples/arguments/advanced.md @@ -7,8 +7,8 @@ search: The [Basics] showed how to access arguments for a command. They are all retrieved as strings which is fine but it we need to say get integers or timestamps the user would have to convert from string to desired type. -To ease the burden on users the `cli` library offers predefined Arg and Args structure to faciliate this -The value of the argument can be retrieved using the command.Arg() function. For e.g +To ease the burden on users the `cli` library offers predefined `{Type}Arg` and `{Type}Args` structure to faciliate this +The value of the argument can be retrieved using the `command.{Type}Arg()` function. For e.g