// Package rags implements rich flag functionality on top of the stdlib flag
// package.
//
// # Features
//
//   - Flag groupings/categories
//   - Flag short aliases
//   - Required flags
//   - Usage information
//   - Produces [flag.FlagSet], for interop with other packages
//   - [flag.FlagSet] compatible API
//   - Declarative flag definition via the [Rag] struct
//   - [List], [Set], and [Enum] flag value support for primitive types and
//     custom types.
//
// All of the additional flag functionality can be consumed via drop-in
// replacements for existing [flag.FlagSet] functions, e.g.:
//
//		fs := rags.New("my-cli", flag.ContinueOnError)
//		// Variadic parameter for options allow RagSet.BoolVar to be compatible
//	 	// with existing FlagSet invocations while making additional functionality
//	 	// available.
//		myBool = fs.BoolVar("my-bool", false, "my CLI's bool flag",
//			rags.WithCategory("mine"),
//			rags.WithRequired(),
//			rags.WithShort("-b")
//		)
//
// # Flag Categories
//
// Flags can be assigned categories that are used for groupings when printing
// usage information. In [RagSet.Usage], flag categories are sorted as such:
//
//  1. Uncategorized flags
//  2. User provided categories
//  3. Global flagspackage rags
//
// # Flag Usage Information
//
// A usage line can be generated for flag's defined using this package:
//
//   - If a flag defines a short flag, it is included inline.
//   - The flag's value is described next to the flag. Blockquoted flag type
//     annotations as described in the stdlib (see [UnquoteUsage]) is supported.
//     When blockquotes aren't used, flag [Value] implementations can provide
//     their own annotation by implementing [TypedValue].
//
// Example:
//
//	# blockquoted identifier
//	-c, --config file	configuration `file` to load
//
//	# value implements Type()
//	-c, --config config(s)	bazel configuration profiles to apply
//
//	# built-in flag types
//	-c, --config string	configuration file to load
package rags