From e6fdf13dd8cbcc41faf914f95ac4f923efd7d92d Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Fri, 22 Sep 2023 16:39:42 +0200 Subject: [PATCH] doc Signed-off-by: Frederic BIDON --- README.md | 39 ++++++++++++++++----------------------- docs/about.md | 14 ++++++++++++++ 2 files changed, 30 insertions(+), 23 deletions(-) create mode 100644 docs/about.md diff --git a/README.md b/README.md index b6f6eb7..9ece1b9 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ > > The main idea is to simplify the pflag interface, with less things to remember about flag types. > -> So this is not a fork or drop-in replacement, but an extension of the `pflag` functionality. +> So this is not a fork or drop-in replacement, but rather an extension of the `pflag` functionality. ## Usage @@ -43,7 +43,7 @@ fs.Var(intFlag, "integer", "integer value") // register the flag in pflag fl _ = fs.Parse([]string{"--integer", 10}) // parse command line arguments -fmt.Println(intFlag.GetValue()) +fmt.Println(intFlag.GetValue()) // the flag knows the type of the value ``` With `pflag` this piece of code would look like: @@ -62,7 +62,7 @@ fs.IntVar(&flagVal, "integer", "integer value") // register the flag in pflag f _ = fs.Parse([]string{"--integer", 10}) // parse command line arguments -fmt.Println(fs.GetInt("integer")) +fmt.Println(fs.GetInt("integer")) // has to know an integer type is expected ``` You may take a look at [more examples](example_values_test.go), with slices and maps. @@ -71,30 +71,23 @@ You may take a look at [more examples](example_values_test.go), with slices and This package provides a unified approach to strongly typed flags, using go generics. -This way, we no longer have to register CLI flags using dozen of type-specific methods. +This way, we no longer have to register CLI flags using dozen of type-specific methods, just three: +* `NewFlagValue()`: for scalar values +* `NewFlagSliceValue()`: for flags as lists +* `NewFlagMapValue()`: for flags as map (e.g. key=value pairs) -The flag building logic is now consistent for single values, slices and maps of all types. +The flag building logic is consistent for single values, slices and maps of all types. -All primitive types (yes, complex too!) are supported. -All common types handled by `pflag` (`time.Duration`, `net.IP`, etc..) are also supported. -I have also added `time.Time`. +* **All primitive types** (yes, complex too!) are supported. +* All common types handled by `pflag` (`time.Duration`, `net.IP`, etc..) are also supported. +* I have also added `time.Time` +* Supprot extensions built for `pflag` (arbitrary types with the `pflag.Value` interface) -Slight variations in the semantics for a flag with a given underlying type may be fine-tuned with some options. -There is an `extensions` sub-package to contribute some more custom flag types. -This one is initially populated with a `byte-size` flag. See [the example](extensions/example_test.go). - -## About CLI flags - -There are quite many existing CLI flag handling libraries out there. +Variations in the semantics for a flag with a given underlying type may be fine-tuned with options. -The most popular one is (by a mile) `github.com/spf13/pflag` (originally forked from `githb.com/ogier/pflag`). -It is used by other very popular packages `spf13/viper` and `spf13/cobra`. - -The second most popular (by number of imports by public repositories) is `github.com/jessevdk/go-flags`. - -The approach proposed by our package is built on top `github.com/spf13/pflag` and remains interoperable with other -great CLI-building libraries such as `viper` and `cobra`. +There is an `extensions` sub-package to contribute some more custom flag types. +This one is initially populated with a `byte-size` flag. See [the example](extensions/example_test.go). -[Various packages and approaches to dealing with flags](docs/approaches.md) +## [About CLI flags](./docs/about.md) diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 0000000..661f990 --- /dev/null +++ b/docs/about.md @@ -0,0 +1,14 @@ +# About CLI flags + +There are many existing CLI flag handling libraries out there. + +The most popular one by a mile is `github.com/spf13/pflag` (originally forked from `githb.com/ogier/pflag`). + +It is used by other very popular packages `spf13/viper` and `spf13/cobra`. + +The second most popular (by number of imports by public repositories) is `github.com/jessevdk/go-flags`. + +The approach proposed by our package is built on top `github.com/spf13/pflag` and remains interoperable with other +great CLI-building libraries such as `viper` and `cobra`. + +[Various packages and approaches to dealing with flags](./approaches.md)