types

type BuiltinFlags struct {
	Help       *flags.BoolFlag // 标志-帮助
	Version    *flags.BoolFlag // 标志-版本
	Completion *flags.EnumFlag // 标志-自动完成
	NameMap    sync.Map        // 内置标志名称映射
}

type CmdConfig struct {
	// 版本信息
	Version string

	// 自定义描述
	Description string

	// 自定义的完整命令行帮助信息
	Help string

	// 自定义用法格式说明
	UsageSyntax string

	// 模块帮助信息
	ModuleHelps string

	// logo文本
	LogoText string

	// 备注内容切片
	Notes []string

	// 示例信息切片
	Examples []ExampleInfo

	// 是否使用中文帮助信息
	UseChinese bool

	// 控制内置标志是否自动退出
	ExitOnBuiltinFlags bool

	// 控制是否启用自动补全功能
	EnableCompletion bool
}

type CmdContext struct {
	// 长命令名称
	LongName string
	// 短命令名称
	ShortName string

	// 标志注册表, 统一管理标志的元数据
	FlagRegistry *flags.FlagRegistry
	// 底层flag集合, 处理参数解析
	FlagSet *flag.FlagSet

	// 命令行参数(非标志参数)
	Args []string
	// 是否已经解析过参数
	Parsed atomic.Bool
	// 用于确保参数解析只执行一次
	ParseOnce sync.Once
	// 读写锁
	Mutex sync.RWMutex

	// 子命令上下文切片
	SubCmds []*CmdContext
	// 子命令映射表
	SubCmdMap map[string]*CmdContext
	// 父命令上下文
	Parent *CmdContext

	// 配置信息
	Config *CmdConfig

	// 内置标志结构体
	BuiltinFlags *BuiltinFlags

	// ParseHook 解析阶段钩子函数
	// 在标志解析完成后、子命令参数处理后调用
	//
	// 参数:
	//   - 当前命令上下文
	//
	// 返回值:
	//   - error: 错误信息, 非nil时会中断解析流程
	//   - bool: 是否需要退出程序
	ParseHook func(*CmdContext) (error, bool)
}

type ExampleInfo struct {
	Description string // 示例描述
	Usage       string // 示例使用方式
}