1 // Package rags implements rich flag functionality on top of the stdlib flag 2 // package. 3 // 4 // # Features 5 // 6 // - Flag groupings/categories 7 // - Flag short aliases 8 // - Required flags 9 // - Usage information 10 // - Produces [flag.FlagSet], for interop with other packages 11 // - [flag.FlagSet] compatible API 12 // - Declarative flag definition via the [Rag] struct 13 // - [List], [Set], and [Enum] flag value support for primitive types and 14 // custom types. 15 // 16 // All of the additional flag functionality can be consumed via drop-in 17 // replacements for existing [flag.FlagSet] functions, e.g.: 18 // 19 // fs := rags.New("my-cli", flag.ContinueOnError) 20 // // Variadic parameter for options allow RagSet.BoolVar to be compatible 21 // // with existing FlagSet invocations while making additional functionality 22 // // available. 23 // myBool = fs.BoolVar("my-bool", false, "my CLI's bool flag", 24 // rags.WithCategory("mine"), 25 // rags.WithRequired(), 26 // rags.WithShort("-b") 27 // ) 28 // 29 // # Flag Categories 30 // 31 // Flags can be assigned categories that are used for groupings when printing 32 // usage information. In [RagSet.Usage], flag categories are sorted as such: 33 // 34 // 1. Uncategorized flags 35 // 2. User provided categories 36 // 3. Global flagspackage rags 37 // 38 // # Flag Usage Information 39 // 40 // A usage line can be generated for flag's defined using this package: 41 // 42 // - If a flag defines a short flag, it is included inline. 43 // - The flag's value is described next to the flag. Blockquoted flag type 44 // annotations as described in the stdlib (see [UnquoteUsage]) is supported. 45 // When blockquotes aren't used, flag [Value] implementations can provide 46 // their own annotation by implementing [TypedValue]. 47 // 48 // Example: 49 // 50 // # blockquoted identifier 51 // -c, --config file configuration `file` to load 52 // 53 // # value implements Type() 54 // -c, --config config(s) bazel configuration profiles to apply 55 // 56 // # built-in flag types 57 // -c, --config string configuration file to load 58 package rags 59