CliAddKind = enum
  caEqual,                  ## `--key=value`
  caPlusEqual,              ## `--key+=value`
  caColon,                  ## `--key:value`
  caMinusEqual,             ## `--key-=value`
  caNoSep,                  ## `-kvalue`
  caCarentEqual,            ## `--key^=value`
  caEqualNone                ## `--key=`

CliErrPolicy = enum
  ceColorDiagnostics, ceJsonDiagnostics

CliFail = object
  argStr*: string
  case kind*: CliFailKind
  of cfMultiFail:
      subFails*: seq[CliFail]

  of cfNoSuchSelector:
      selector*: string

  of cfNoSuchOption:
      option*: string

  else:
      nil

  jsonMsg*: JsonNode
  strMsg*: ColoredText

CliFailKind = enum
  cfNoSuchOption, cfNoSuchSelector, cfBadCliSyntax, cfBadCliValue,
  cfMissingValue, cfMultiFail

CliOpt = object
  globalPos*: int            ## Absolute position in the input sequence of arguments
  rawStr*: string            ## Raw string value of the command (with all dashes etc)
  kind*: CliOptKind
  shortDash*: bool
  keyPath*: seq[string]      ## Full path to the key. `--cc.exe=json` has path
                             ## `["cc", "exe"]`, regular `--help` has path
                             ## `["help"]`
  keySelect*: string         ## Selector value used in bracket options -
                             ## `--warn[Init]:on` has `keySelector = "Init"`
  valStr*: string            ## String value of the command
  addKind*: CliAddKind
  optKind*: CliOptKind
  specialKind*: CliSpecialKind

CliOptKind = enum
  coFlag,                   ## `--flag`
  coDotFlag,                ## `--help.json`
  coBracketFlag,            ## `--warn[Relocate]`
  coOpt,                    ## `--opt:value`
  coDotOpt,                 ## `--clang.exe:/bin/clang10`
  coBracketOpt,             ## `--warn[Noinit]:true`
  coArgument, coSpecial, coCommand

CliParseConfig = object
  shortOpts*: set[char]
  specialStart*: seq[string]
  blockedAddKinds*: set[CliAddKind]
  errPolicy*: set[CliErrPolicy]
  hasValue*: proc (arg: CliOpt): bool {.noSideEffect.}
  seqSeparator*: string

CliSpecialKind = enum
  cskVerbatimNext, cskStdinAlias

coBracketKinds = {coBracketFlag, coBracketOpt}

coDashedKinds = {coFlag..coBracketOpt}

coFlagKinds = {coFlag..coBracketFlag}

coOptionKinds = {coOpt..coBracketOpt}

defaulCliParseConfig = (shortOpts: {}, specialStart: [], blockedAddKinds: {},
                        errPolicy: {}, hasValue: (nil, nil), seqSeparator: ",")

func `$`(cli: CliOpt): string {....raises: [ValueError], tags: [].}

func canAddValue(opt: CliOpt): bool {....raises: [], tags: [].}

func classifyCliArg(arg: string; config: CliParseConfig): CliOptKind {.
    ...raises: [], tags: [].}

func cliParse(arg: string; res: var float; config: CliParseConfig): Option[
    CliFail] {....raises: [], tags: [].}

func cliParse(arg: string; res: var int; config: CliParseConfig): Option[CliFail] {.
    ...raises: [], tags: [].}

func cliParse(arg: string; res: var string; config: CliParseConfig): Option[
    CliFail] {....raises: [], tags: [].}

func cliParse[En: enum](arg: string; res: var En; config: CliParseConfig): Option[
    CliFail]

func cliParse[T](arg: string; res: var seq[T]; config: CliParseConfig): Option[
    CliFail]

func key(opt: CliOpt): string {....raises: [], tags: [].}

func lispRepr(cli: CliOpt): ColoredText {....raises: [ValueError], tags: [].}

func needsValue(opt: CliOpt): bool {....raises: [], tags: [].}

func parseArgument(arg: string; config: CliParseConfig): CliOpt {....raises: [],
    tags: [].}

func parseCliOpts(args: seq[string]; config: CliParseConfig = CliParseConfig()): tuple[
    parsed: seq[CliOpt], failed: seq[CliFail]] {.
    ...raises: [Exception, UnexpectedKindError], tags: [RootEffect].}

func parseCommand(arg: string; config: CliParseConfig): CliOpt {....raises: [],
    tags: [].}

func parseFlag(arg: string; config: CliParseConfig): CliOpt {....raises: [],
    tags: [].}

func parseOpt(arg: string; config: CliParseConfig): CliOpt {....raises: [],
    tags: [].}

func parseSpecial(arg: string; config: CliParseConfig): CliOpt {.
    ...raises: [UnexpectedKindError], tags: [].}

func splitCliArgs(args: seq[string]; config: CliParseConfig): seq[string] {.
    ...raises: [], tags: [].}

func splitFlag(arg: string; config: CliParseConfig): tuple[keyPath: seq[string],
    keySelector: string, value: string, dashes: string] {....raises: [], tags: [].}

func value(opt: CliOpt): string {....raises: [], tags: [].}

macro scanpFull(str: typed; pattern: varargs[untyped]): untyped

macro scanpFull(str: typed; start: int; pattern: varargs[untyped]): untyped