diff --git a/docs/v3/examples/arguments/advanced.md b/docs/v3/examples/arguments/advanced.md new file mode 100644 index 0000000000..0d1dad3857 --- /dev/null +++ b/docs/v3/examples/arguments/advanced.md @@ -0,0 +1,224 @@ +--- +tags: + - v3 +search: + boost: 2 +--- + +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 + + +```go +package main + +import ( + "fmt" + "log" + "os" + "context" + + "github.com/urfave/cli/v3" +) + +func main() { + cmd := &cli.Command{ + Arguments: []cli.Argument{ + &cli.IntArg{ + Name: "someint", + }, + }, + Action: func(ctx context.Context, cmd *cli.Command) error { + fmt.Printf("We got %d", cmd.IntArg("someint")) + return nil + }, + } + + if err := cmd.Run(context.Background(), os.Args); err != nil { + log.Fatal(err) + } +} +``` + +Running this program with an argument gives the following output + +```sh-session +$ greet 10 +We got 10 +``` + +Instead of using the cmd.XXXArg() function to retrieve the argument value a destination for the argument can be set +for e.g + + +```go +package main + +import ( + "fmt" + "log" + "os" + "context" + + "github.com/urfave/cli/v3" +) + +func main() { + var ival int + cmd := &cli.Command{ + Arguments: []cli.Argument{ + &cli.IntArg{ + Name: "someint", + Destination: &ival, + }, + }, + Action: func(ctx context.Context, cmd *cli.Command) error { + fmt.Printf("We got %d", ival) + return nil + }, + } + + if err := cmd.Run(context.Background(), os.Args); err != nil { + log.Fatal(err) + } +} +``` + +Some of the basic types arguments suported are + +- `FloatArg` +- `IntArg` +- `Int8Arg` +- `Int16Arg` +- `Int32Arg` +- `Int64Arg` +- `StringArg` +- `UintArg` +- `Uint8Arg` +- `Uint16Arg` +- `Uint32Arg` +- `Uint64Arg` +- `TimestampArg` + +This is ok for single value arguments. Any number of these single value arguments can be concatenated in the `Arguments` +slice field of `Command`. + +The library also support multi value arguments for e.g + + +```go +package main + +import ( + "fmt" + "log" + "os" + "context" + + "github.com/urfave/cli/v3" +) + +func main() { + cmd := &cli.Command{ + Arguments: []cli.Argument{ + &cli.IntArgs{ + Name: "someint", + Min: 0, + Max: -1, + }, + }, + Action: func(ctx context.Context, cmd *cli.Command) error { + fmt.Println("We got ", cmd.IntArgs("someint")) + return nil + }, + } + + if err := cmd.Run(context.Background(), os.Args); err != nil { + log.Fatal(err) + } +} +``` + +Some things to note about multi value arguments + +1. They have XXXArgs type instead of XXXArg to differentiate them from single value arguments +2. The Max field needs to be defined to a non zero value without which it cannot be parsed +3. Max field value needs to be greater then the Min field value + +As with single value args the destination field can be set + + +```go +package main + +import ( + "fmt" + "log" + "os" + "context" + + "github.com/urfave/cli/v3" +) + +func main() { + var ivals []int + cmd := &cli.Command{ + Arguments: []cli.Argument{ + &cli.IntArgs{ + Name: "someint", + Min: 0, + Max: -1, + Destination: &ivals, + }, + }, + Action: func(ctx context.Context, cmd *cli.Command) error { + fmt.Println("We got ", ivals) + return nil + }, + } + + if err := cmd.Run(context.Background(), os.Args); err != nil { + log.Fatal(err) + } +} +``` + +Following multi value arguments are supported + +- `FloatArgs` +- `IntArgs` +- `Int8Args` +- `Int16Args` +- `Int32Args` +- `Int64Args` +- `StringArgs` +- `UintArgs` +- `Uint8Args` +- `Uint16Args` +- `Uint32Args` +- `Uint64Args` +- `TimestampArgs` + +It goes without saying that the chain of arguments set in the Arguments slice need to be consistent. Generally a glob +argument(max=-1) should be set for the argument at the end of the slice. To glob args we arent interested in we coud add +the following to the end of the Arguments slice and retrieve them as a slice + +``` + &StringArgs{ + Max: -1, + }, +``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 041c7131ad..34b4e68471 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -29,7 +29,7 @@ nav: - Advanced: v3/examples/flags/advanced.md - Arguments: - Basics: v3/examples/arguments/basics.md - #- Advanced: v3/examples/arguments/advanced.md + - Advanced: v3/examples/arguments/advanced.md - Subcommands: - Basics: v3/examples/subcommands/basics.md - Categories: v3/examples/subcommands/categories.md