module flag

import v.ast

struct FlagData {
    raw        string @[required]
    field_name string @[required]
    delimiter  string
    name       string
    arg        ?string
    pos        int
    repeats    int = 1
}

struct FlagContext {
    raw       string @[required] // raw arg array entry. E.g.: `--id=val`
    delimiter string // usually `'-'`
    name      string // either struct field name or what is defined in `@[long: <name>]`
    next      string // peek at what is the next flag/arg
    pos       int    // position in arg array
}

pub enum ParseMode {
    strict  // return errors for unknown or malformed flags per default
    relaxed // relax flag match errors and add them to `no_match` list instead
}

pub enum Style {
    short         // Posix short only, allows multiple shorts -def is `-d -e -f` and "sticky" arguments e.g.: `-ofoo` = `-o foo`
    long          // GNU style long option *only*. E.g.: `--name` or `--name=value`
    short_long    // extends `posix` style shorts with GNU style long options: `--flag` or `--name=value`
    v             // V style flags as found in flags for the `v` compiler. Single flag denote `-` followed by string identifier e.g.: `-verbose`, `-name value`, `-v`, `-n value` or `-d ident=value`
    v_flag_parser // V `flag.FlagParser` style flags as supported by `flag.FlagParser`. Long flag denote `--` followed by string identifier e.g.: `--verbose`, `--name value`, `-v` or `-n value`.
    go_flag       // GO `flag` module style. Single flag denote `-` followed by string identifier e.g.: `-verbose`, `-name value`, `-v` or `-n value` and both long `--name value` and GNU long `--name=value`
    cmd_exe       // `cmd.exe` style flags. Single flag denote `/` followed by lower- or upper-case character
}

struct StructInfo {
    name   string            // name of the struct itself
    attrs  map[string]string // collection of `@[x: y]` sat on the struct, read via reflection
    fields map[string]StructField
}

@[flag]
pub enum FieldHints {
    is_bool
    is_array
    is_ignore
    is_int_type
    has_tail
    short_only
    can_repeat
}

// StructField is a representation of the data collected via reflection on the input `T` struct.
// `match_name` is resolved upon reflection and represents the longest flag name value the user wants
// to be mapped to this field. If users has indicated that they want to match a field as a short/abbrevation flag
// `short` is accounted instead of `match_name`
struct StructField {
    name       string // name of the field on the struct, *not used* for resolving mappings, use `match_name`
    match_name string // match_name is either `name` or the value of `@[long: x]` or `@[only: x]`
    short      string // single char short alias of field, sat via `@[short: x]` or `@[only: x]`
    hints      FieldHints = FieldHints.zero()
    attrs      map[string]string // collection of `@[x: y]` sat on the field, read via reflection
    type_name  string
    doc        string // documentation string sat via `@[xdoc: x y z]`
}

fn assign_single_flag_value[T](mut target T, default_value T, f FlagData, struct_name string, field_name string) ! {
    _ = target
    a_or_r := f.arg or { '${f.repeats}' }
    $if T is int {
        if !a_or_r.is_int() {
            return error('can not assign non-integer value `${a_or_r}` from flag `${f.raw}` to `${struct_name}.${field_name}`')
        }
        target = a_or_r.int()
    } $else $if T is i64 {
        if !a_or_r.is_int() {
            return error('can not assign non-integer value `${a_or_r}` from flag `${f.raw}` to `${struct_name}.${field_name}`')
        }
        target = a_or_r.i64()
    } $else $if T is u64 {
        if !a_or_r.is_int() {
            return error('can not assign non-integer value `${a_or_r}` from flag `${f.raw}` to `${struct_name}.${field_name}`')
        }
        target = a_or_r.u64()
    } $else $if T is i32 {
        if !a_or_r.is_int() {
            return error('can not assign non-integer value `${a_or_r}` from flag `${f.raw}` to `${struct_name}.${field_name}`')
        }
        target = a_or_r.i32()
    } $else $if T is u32 {
        if !a_or_r.is_int() {
            return error('can not assign non-integer value `${a_or_r}` from flag `${f.raw}` to `${struct_name}.${field_name}`')
        }
        target = a_or_r.u32()
    } $else $if T is i16 {
        if !a_or_r.is_int() {
            return error('can not assign non-integer value `${a_or_r}` from flag `${f.raw}` to `${struct_name}.${field_name}`')
        }
        target = a_or_r.i16()
    } $else $if T is u16 {
        if !a_or_r.is_int() {
            return error('can not assign non-integer value `${a_or_r}` from flag `${f.raw}` to `${struct_name}.${field_name}`')
        }
        target = a_or_r.u16()
    } $else $if T is i8 {
        if !a_or_r.is_int() {
            return error('can not assign non-integer value `${a_or_r}` from flag `${f.raw}` to `${struct_name}.${field_name}`')
        }
        target = a_or_r.i8()
    } $else $if T is u8 {
        if !a_or_r.is_int() {
            return error('can not assign non-integer value `${a_or_r}` from flag `${f.raw}` to `${struct_name}.${field_name}`')
        }
        target = a_or_r.u8()
    } $else $if T is f32 {
        target = f.arg or { return error('failed appending ${f.raw} to ${field_name}') }
            .f32()
    } $else $if T is f64 {
        target = f.arg or { return error('failed appending ${f.raw} to ${field_name}') }
            .f64()
    } $else $if T is bool {
        if arg := f.arg {
            return error('can not assign `${arg}` to bool field `${field_name}`')
        }
        target = !default_value
    } $else $if T is string {
        target = f.arg or { return error('failed appending ${f.raw} to ${field_name}') }
            .str()
    } $else {
        return error('field type: ${T.name} for ${field_name} is not supported')
    }
}

fn append_multi_flag_value[T](mut target T, f FlagData, field_name string) ! {
    $if T is []string {
        target << f.arg or { return error('failed appending ${f.raw} to ${field_name}') }
            .str()
    } $else $if T is []int {
        target << f.arg or { return error('failed appending ${f.raw} to ${field_name}') }
            .int()
    } $else $if T is []i64 {
        target << f.arg or { return error('failed appending ${f.raw} to ${field_name}') }
            .i64()
    } $else $if T is []u64 {
        target << f.arg or { return error('failed appending ${f.raw} to ${field_name}') }
            .u64()
    } $else $if T is []i32 {
        target << f.arg or { return error('failed appending ${f.raw} to ${field_name}') }
            .i32()
    } $else $if T is []u32 {
        target << f.arg or { return error('failed appending ${f.raw} to ${field_name}') }
            .u32()
    } $else $if T is []i16 {
        target << f.arg or { return error('failed appending ${f.raw} to ${field_name}') }
            .i16()
    } $else $if T is []u16 {
        target << f.arg or { return error('failed appending ${f.raw} to ${field_name}') }
            .u16()
    } $else $if T is []i8 {
        target << f.arg or { return error('failed appending ${f.raw} to ${field_name}') }
            .i8()
    } $else $if T is []u8 {
        target << f.arg or { return error('failed appending ${f.raw} to ${field_name}') }
            .u8()
    } $else $if T is []f32 {
        target << f.arg or { return error('failed appending ${f.raw} to ${field_name}') }
            .f32()
    } $else $if T is []f64 {
        target << f.arg or { return error('failed appending ${f.raw} to ${field_name}') }
            .f64()
    } $else {
        return error('field type: ${T.name} for multi value ${field_name} is not supported')
    }
}

fn (sf StructField) shortest_match_name() ?string {
    mut name := sf.short // if `short` is sat it takes precedence over `match_name`
    if name == '' && sf.match_name.len == 1 {
        name = sf.match_name
    }
    if name != '' {
        return name
    }
    return none
}

@[params]
pub struct ParseConfig {
pub:
    delimiter string    = '-'         // delimiter used for flags
    mode      ParseMode = .strict     // return errors for unknown or malformed flags per default
    style     Style     = .short_long // expected flag style
    stop      ?string // single, usually '--', string that stops parsing flags/options
    skip      u16     // skip this amount in the input argument array, usually `1` for skipping executable or subcmd entry
}

@[params]
pub struct DocConfig {
pub:
    delimiter string = '-'         // delimiter used for flags
    style     Style  = .short_long // expected flag style
pub mut:
    name        string            // application name
    version     string            // application version
    description string            // application description
    footer      string            // application description footer written after auto-generated flags list/ field descriptions
    layout      DocLayout         // documentation layout
    options     DocOptions        // documentation options
    fields      map[string]string // doc strings for each field (overwrites @[doc: xxx] attributes)
}

@[flag]
pub enum Show {
    name
    version
    flags
    flag_type
    flag_hint
    description
    flags_header
    footer
}

pub struct DocLayout {
pub mut:
    description_padding int = 28
    description_width   int = 50
    flag_indent         int = 2
}

pub struct DocOptions {
pub mut:
    flag_header string = '\nOptions:'
    compact     bool
    show        Show = ~Show.zero()
}

// max_width returns the total width of the `DocLayout`.
pub fn (dl DocLayout) max_width() int {
    return dl.flag_indent + dl.description_padding + dl.description_width
}

pub struct FlagMapper {
pub:
    config ParseConfig @[required]
    input  []string    @[required]
mut:
    si                   StructInfo
    handled_pos          []int // tracks handled positions in the `input` args array. NOTE: can contain duplicates
    field_map_flag       map[string]FlagData
    array_field_map_flag map[string][]FlagData
    no_match             []int // indicies of unmatched flags in the `input` array
}

@[if trace_flag_mapper ?]
fn trace_println(str string) {
    println(str)
}

@[if trace_flag_mapper ? && debug]
fn trace_dbg_println(str string) {
    println(str)
}

// dbg_match returns a debug string with data about the mapping of a flag to a field
fn (fm FlagMapper) dbg_match(flag_ctx FlagContext, field StructField, arg string, field_extra string) string {
    struct_name := fm.si.name
    extra := if field_extra != '' { '/' + field_extra } else { '' }
    return '${struct_name}.${field.name}/${field.short}${extra} in ${flag_ctx.raw}/${flag_ctx.name} = `${arg}`'
}

fn normalize_attr_value(value string) string {
    trimmed := value.trim_space()
    if trimmed.len > 1 {
        if (trimmed[0] == `'` && trimmed[trimmed.len - 1] == `'`)
            || (trimmed[0] == `"` && trimmed[trimmed.len - 1] == `"`) {
            return trimmed[1..trimmed.len - 1]
        }
    }
    return trimmed
}

fn (mut fm FlagMapper) add_array_flag(field_name string, flag_data FlagData) {
    if field_name !in fm.array_field_map_flag {
        fm.array_field_map_flag[field_name] = []FlagData{}
    }
    fm.array_field_map_flag[field_name] << flag_data
}

fn (fm FlagMapper) get_struct_info[T]() !StructInfo {
    mut struct_fields := map[string]StructField{}
    mut struct_attrs := map[string]string{}
    mut struct_name := ''
    mut used_names := []string{}
    $if T is $struct {
        struct_name = T.name
        trace_println('${@FN}: mapping struct "${struct_name}"...')

        $for st_attr in T.attributes {
            if st_attr.has_arg && st_attr.kind == .string {
                struct_attrs[st_attr.name.trim_space()] = st_attr.arg.trim(' ')
            }
        }
        // Handle positional first so they can be marked as handled
        $for field in T.fields {
            mut hints := FieldHints.zero()
            mut match_name := field.name.replace('_', '-')
            trace_println('${@FN}: field "${field.name}":')
            mut attrs := map[string]string{}
            for attr in field.attrs {
                trace_println('\tattribute: "${attr}"')
                if attr.contains(':') {
                    attr_name, attr_value := attr.split_once(':') or { '', '' }
                    attrs[attr_name.trim_space()] = normalize_attr_value(attr_value)
                } else {
                    attrs[attr.trim(' ')] = 'true'
                }
            }
            if long_alias := attrs['long'] {
                match_name = long_alias.replace('_', '-')
            }
            if only := attrs['only'] {
                if only.len == 0 {
                    return error('attribute @[only] on ${struct_name}.${match_name} can not be empty, use @[only: x]')
                } else if only.len == 1 {
                    hints.set(.short_only)
                    attrs['short'] = only
                    if only in used_names {
                        return error('attribute @[only: ${only}] on ${struct_name}.${field.name}, "${only}" is already in use')
                    }
                } else if only.len > 1 {
                    match_name = only
                }
            }

            mut short := ''
            if short_alias := attrs['short'] {
                if short_alias.len != 1 {
                    return error('attribute @[short: ${short}] on ${struct_name}.${field.name} can only be a single character')
                }
                short = short_alias

                if short in used_names {
                    return error('attribute @[short: ${short_alias}] on ${struct_name}.${field.name}, "${short}" is already in use')
                }
                used_names << short
            }

            trace_println('\tmatch name: "${match_name}"')
            used_names << match_name

            if field.typ in [
                int(ast.int_type),
                int(ast.i64_type),
                int(ast.u64_type),
                int(ast.i32_type),
                int(ast.u32_type),
                int(ast.i16_type),
                int(ast.u16_type),
                int(ast.i8_type),
                int(ast.u8_type),
            ] {
                hints.set(.is_int_type)
            }

            if _ := attrs['repeats'] {
                hints.set(.can_repeat)
            }
            if _ := attrs['tail'] {
                hints.set(.has_tail)
            }
            if _ := attrs['ignore'] {
                hints.set(.is_ignore)
            }

            if field.typ == int(ast.bool_type) {
                trace_println('\tfield "${field.name}" is a bool')
                hints.set(.is_bool)
            }
            if field.is_array {
                trace_println('\tfield "${field.name}" is array')
                hints.set(.is_array)
            }

            if !hints.has(.is_int_type) && hints.has(.can_repeat) {
                return error('`@[repeats] can only be used on integer type fields like `int`, `u32` etc.')
            }

            mut doc := ''
            // `xdoc` was chosen because of `vfmt` sorting attributes alphabetically - so to avoid cluttering attributes
            // we want the doc strings to be among the last attributes. To make it flexible to users we provide
            // `$d('v:flag:doc_attr','xdoc')` to let users tweak it.
            if docs := attrs[$d('v:flag:doc_attr', 'xdoc')] {
                trace_println('\tdoc for field "${field.name}": ${docs}')
                doc = docs
            }

            struct_fields[field.name] = StructField{
                name:       field.name
                match_name: match_name
                hints:      hints
                short:      short
                attrs:      attrs
                type_name:  typeof(field).name
                doc:        doc
            }
        }
    } $else {
        return error('the type `${T.name}` can not be decoded.')
    }

    return StructInfo{
        name:   struct_name
        attrs:  struct_attrs
        fields: struct_fields
    }
}

fn (m map[string]FlagData) query_flag_with_name(name string) ?FlagData {
    for _, flag_data in m {
        if flag_data.name == name {
            return flag_data
        }
    }
    return none
}

// to_struct returns `T` with field values sat to any matching flags in `input`.
// to_struct also returns any flags from `input`, in order of appearance, that could *not* be matched
// with any field on `T`.
pub fn to_struct[T](input []string, config ParseConfig) !(T, []string) {
    mut fm := FlagMapper{
        config: config
        input:  input
    }
    fm.parse[T]()!
    st := fm.to_struct[T](none)!
    return st, fm.no_matches()
}

// using returns `defaults` with field values overwritten with any matching flags in `input`.
// Any field that could *not* be matched with a flag will have the same value as the
// field(s) passed as `defaults`.
// using also returns any flags from `input`, in order of appearance, that could *not* be matched
// with any field on `T`.
pub fn using[T](defaults T, input []string, config ParseConfig) !(T, []string) {
    mut fm := FlagMapper{
        config: config
        input:  input
    }
    fm.parse[T]()!
    st := fm.to_struct[T](defaults)!
    return st, fm.no_matches()
}

// to_doc returns a "usage" style documentation `string` generated from attributes on `T` or via the `dc` argument.
pub fn to_doc[T](dc DocConfig) !string {
    mut fm := FlagMapper{
        config: ParseConfig{
            delimiter: dc.delimiter
            style:     dc.style
        }
        input:  []
    }
    fm.si = fm.get_struct_info[T]()!
    return fm.to_doc(dc)!
}

// no_matches returns any flags from the `input` array, in order of appearance, that could *not* be matched against any fields.
// This method should be called *after* `to_struct[T]()`.
pub fn (fm FlagMapper) no_matches() []string {
    mut non_matching := []string{}
    for i in fm.no_match {
        non_matching << fm.input[i]
    }
    return non_matching
}

// parse parses `T` to an internal data representation.
pub fn (mut fm FlagMapper) parse[T]() ! {
    config := fm.config
    style := config.style
    delimiter := config.delimiter
    args := fm.input

    trace_println('${@FN}: parsing ${args}')
    if config.skip > 0 {
        // skip X entries. Could be the "exe", "executable" or "subcmd" - or more if the user wishes
        for i in 0 .. int(config.skip) {
            fm.handled_pos << i
        }
    }

    // Gather runtime information about T
    fm.si = fm.get_struct_info[T]()!
    struct_name := fm.si.name

    // Find the position of the last flag in `input`
    mut pos_last_flag := -1
    for pos, arg in args {
        if arg.starts_with(delimiter) {
            pos_last_flag = pos
        }
    }

    for pos, arg in args {
        if arg == '' {
            fm.no_match << pos
            continue
        }
        mut pos_is_handled := pos in fm.handled_pos

        if !pos_is_handled {
            // Stop parsing as soon as possible if `--` (or user defined) stop option is sat and encountered
            if arg == config.stop or { '' } {
                trace_println('${@FN}: reached option stop (${config.stop}) at index ${pos}')
                // record all positions after this as not matching, unless pos is the last entry
                if pos < args.len - 1 {
                    for unused_pos in pos + 1 .. args.len {
                        fm.no_match << unused_pos
                    }
                }
                break
            }
        }

        // peek next arg
        mut next := if pos + 1 < args.len { args[pos + 1] } else { '' }

        // Parse arg entry (potential flag)
        mut is_flag := false // `flag` starts with `-` (default value) or user defined
        mut flag_name := ''
        if arg.starts_with(delimiter) {
            is_flag = true
            flag_name = arg.trim_left(delimiter)
            // Parse GNU (GO `flag`) `--name=value`
            if style in [.long, .short_long, .go_flag] {
                flag_name = flag_name.all_before('=')
            }
        }

        // A flag, find best matching field in struct, if any
        if is_flag {
            // Figure out and validate used delimiter
            used_delimiter := arg.all_before(flag_name)
            is_long_delimiter := used_delimiter.count(delimiter) == 2
            is_short_delimiter := used_delimiter.count(delimiter) == 1
            is_invalid_delimiter := !is_long_delimiter && !is_short_delimiter
            if is_invalid_delimiter {
                if config.mode == .relaxed {
                    fm.no_match << pos
                    continue
                }
                return error('invalid delimiter `${used_delimiter}` for flag `${arg}`')
            }
            if is_long_delimiter {
                if style == .v {
                    if config.mode == .relaxed {
                        fm.no_match << pos
                        continue
                    }
                    return error('long delimiter `${used_delimiter}` encountered in flag `${arg}` in ${style} (V) style parsing mode. Maybe you meant `.v_flag_parser`?')
                }
                if style == .short {
                    if config.mode == .relaxed {
                        fm.no_match << pos
                        continue
                    }
                    return error('long delimiter `${used_delimiter}` encountered in flag `${arg}` in ${style} (POSIX) style parsing mode')
                }
            }

            if is_short_delimiter {
                if style == .long {
                    if config.mode == .relaxed {
                        fm.no_match << pos
                        continue
                    }
                    return error('short delimiter `${used_delimiter}` encountered in flag `${arg}` in ${style} (GNU) style parsing mode')
                }
                if style == .short_long && flag_name.len > 1 && flag_name.contains('-') {
                    if config.mode == .relaxed {
                        fm.no_match << pos
                        continue
                    }
                    return error('long name `${flag_name}` used with short delimiter `${used_delimiter}` in flag `${arg}` in ${style} (POSIX/GNU) style parsing mode')
                }
            }

            if flag_name == '' {
                if config.mode == .relaxed {
                    fm.no_match << pos
                    continue
                }
                return error('invalid delimiter-only flag `${arg}`')
            }

            flag_ctx := FlagContext{
                raw:       arg
                delimiter: used_delimiter
                name:      flag_name
                next:      next
                pos:       pos
            }

            // Identify and match short clusters first. Example: `-yxz( arg)` = `-y -x -z( arg)`
            if is_short_delimiter && style in [.short, .short_long] {
                fm.map_posix_short_cluster(flag_ctx)!
            }

            pos_is_handled = pos in fm.handled_pos
            if pos_is_handled {
                trace_dbg_println('${@FN}: skipping position "${pos}". Already handled')
                continue
            }

            for _, field in fm.si.fields {
                if field.hints.has(.is_ignore) {
                    trace_dbg_println('${@FN}: skipping field "${field.name}" has an @[ignore] attribute')
                    continue
                }
                // Field already identified, skip
                if _ := fm.field_map_flag[field.name] {
                    trace_dbg_println('${@FN}: skipping field "${field.name}" already identified')
                    continue
                }

                trace_println('${@FN}: matching `${used_delimiter}` ${if is_long_delimiter {
                    '(long)'
                } else {
                    '(short)'
                }} flag "${arg}/${flag_name}" is it matching "${field.name}${if field.short != '' {
                    '/' + field.short
                } else {
                    ''
                }}"?')

                if field.hints.has(.short_only) {
                    trace_println('${@FN}: skipping long delimiter `${used_delimiter}` match for ${struct_name}.${field.name} since it has [only: ${field.short}]')
                }

                if is_short_delimiter {
                    if style in [.short, .short_long] {
                        if fm.map_posix_short(flag_ctx, field)! {
                            continue
                        }
                    } else if style == .v {
                        if fm.map_v(flag_ctx, field)! {
                            continue
                        }
                    } else if style == .v_flag_parser {
                        if fm.map_v_flag_parser_short(flag_ctx, field)! {
                            continue
                        }
                    } else if style == .cmd_exe {
                        if fm.map_cmd_exe(flag_ctx, field)! {
                            continue
                        }
                    } else if style == .go_flag {
                        if fm.map_go_flag_short(flag_ctx, field)! {
                            continue
                        }
                    }
                }

                if is_long_delimiter {
                    // Parse GNU `--name=value`
                    if style in [.long, .short_long] {
                        if fm.map_gnu_long(flag_ctx, field)! {
                            continue
                        }
                    } else if style == .v_flag_parser {
                        if fm.map_v_flag_parser_long(flag_ctx, field)! {
                            continue
                        }
                    } else if style == .go_flag {
                        if fm.map_go_flag_long(flag_ctx, field)! {
                            continue
                        }
                    }
                }
            }
        }

        // Extract any tail(s) according to config
        if pos >= pos_last_flag + 1 {
            trace_dbg_println('${@FN}: (tail) looking for tail match for position "${pos}"...')
            pos_is_handled = pos in fm.handled_pos
            if pos_is_handled {
                trace_dbg_println('${@FN}: (tail) skipping position "${pos}". Already handled')
                continue
            }
            for _, field in fm.si.fields {
                if field.hints.has(.is_ignore) {
                    trace_dbg_println('${@FN}: (tail) skipping field "${field.name}" has an @[ignore] attribute')
                    continue
                }
                // Field already mapped, skip
                if _ := fm.field_map_flag[field.name] {
                    trace_dbg_println('${@FN}: (tail) skipping field "${field.name}" already identified')
                    continue
                }
                if field.hints.has(.has_tail) {
                    trace_dbg_println('${@FN}: (tail) field "${field.name}" has a tail attribute. fm.handled_pos.len: ${fm.handled_pos.len}')
                    last_handled_pos := fm.handled_pos[fm.handled_pos.len - 1] or { 0 }
                    trace_println('${@FN}: (tail) flag `${arg}` last_handled_pos: ${last_handled_pos} pos: ${pos}')
                    if pos == last_handled_pos + 1 || pos == pos_last_flag + 1 {
                        if field.hints.has(.is_array) {
                            fm.add_array_flag(field.name, FlagData{
                                raw:        arg
                                field_name: field.name
                                arg:        ?string(arg) // .arg is used when assigning at comptime to []XYZ
                                pos:        pos
                            })
                        } else {
                            fm.field_map_flag[field.name] = FlagData{
                                raw:        arg
                                field_name: field.name
                                arg:        ?string(arg)
                                pos:        pos
                            }
                        }
                        fm.handled_pos << pos
                        continue
                    }
                }
            }
        }
        if pos !in fm.handled_pos && pos !in fm.no_match {
            fm.no_match << pos
            // TODO: flag_name := arg.trim_left(delimiter) // WHY?
            if already_flag := fm.field_map_flag.query_flag_with_name(arg.trim_left(delimiter)) {
                return error('flag `${arg} ${next}` is already mapped to field `${already_flag.field_name}` via `${already_flag.delimiter}${already_flag.name} ${already_flag.arg or {
                    ''
                }}`')
            }
        }
    }
}

// add name and/or version to doc. Returns true if name or version has been added.
fn doc_add_name_and_version(app_name string, app_version string, options DocOptions, mut docs []string) bool {
    mut name_and_version := ''

    if options.show.has(.name) && app_name != '' {
        name_and_version = app_name
    }

    if options.show.has(.version) && app_version != '' {
        if app_name != '' {
            name_and_version = '${app_name} ${app_version}' // Version string is always name + version
        } else {
            name_and_version = app_version
        }
    }

    if name_and_version != '' {
        docs << '${name_and_version}'

        return true
    }

    return false
}

// to_doc returns a "usage" style documentation `string` generated from the internal data structures generated via the `parse()` function.
pub fn (fm FlagMapper) to_doc(dc DocConfig) !string {
    mut docs := []string{}

    mut app_name := ''
    // resolve name
    if dc.options.show.has(.name) {
        // struct `name: x` attribute, if defined
        if attr_name := fm.si.attrs['name'] {
            app_name = attr_name
        }
        // user passed `name` overrides the attribute and default name
        if dc.name != '' {
            app_name = dc.name
        }
    }

    mut app_version := ''
    // resolve version
    if dc.options.show.has(.version) {
        // struct `version` attribute, if defined
        if attr_version := fm.si.attrs['version'] {
            app_version = attr_version
        }
        // user passed `version` overrides the attribute
        if dc.version != '' {
            app_version = dc.version
        }
    }

    name_and_version := doc_add_name_and_version(app_name, app_version, dc.options, mut docs)

    // Resolve the description if visible
    if dc.options.show.has(.description) {
        mut description := ''
        // Set the description from any `xdoc` (or user defined) from *struct*
        if attr_desc := fm.si.attrs[$d('v:flag:doc_attr', 'xdoc')] {
            description = attr_desc
        }
        // user passed description overrides the attribute
        if dc.description != '' {
            description = dc.description
        }
        if description != '' {
            docs << keep_at_max(description, dc.layout.max_width())
        }
    }

    if dc.options.show.has(.flags) {
        fields_docs := fm.fields_docs(dc)!
        if fields_docs.len > 0 {
            if dc.options.show.has(.flags_header) {
                docs << dc.options.flag_header
            }
            docs << fields_docs
        }
    }

    if dc.options.show.has(.footer) {
        mut footer := ''
        // struct `footer` attribute, if defined
        if attr_footer := fm.si.attrs['footer'] {
            footer = attr_footer
        }
        // user passed `footer` overrides the attribute
        if dc.footer != '' {
            footer = dc.footer
        }
        if footer != '' {
            docs << keep_at_max(footer, dc.layout.max_width())
        }
    }

    if name_and_version {
        mut longest_line := 0
        for doc_line in docs {
            lines := doc_line.split('\n')
            for line in lines {
                if line.len > longest_line {
                    longest_line = line.len
                }
            }
        }
        docs.insert(1, '-'.repeat(longest_line))
    }
    return docs.join('\n')
}

// fields_docs returns every line of the combined field documentation.
pub fn (fm FlagMapper) fields_docs(dc DocConfig) ![]string {
    short_delimiter := match dc.style {
        .short, .short_long, .v, .v_flag_parser, .go_flag, .cmd_exe { dc.delimiter }
        .long { dc.delimiter.repeat(2) }
    }

    long_delimiter := match dc.style {
        .short, .v, .go_flag, .cmd_exe { dc.delimiter }
        .long, .v_flag_parser, .short_long { dc.delimiter.repeat(2) }
    }

    pad_desc := if dc.layout.description_padding < 0 { 0 } else { dc.layout.description_padding }
    empty_padding := ' '.repeat(pad_desc)
    indent_flags := if dc.layout.flag_indent < 0 { 0 } else { dc.layout.flag_indent }
    indent_flags_padding := ' '.repeat(indent_flags)
    desc_max := if dc.layout.description_width < 1 { 1 } else { dc.layout.description_width }

    mut docs := []string{}
    for _, field in fm.si.fields {
        if field.hints.has(.is_ignore) {
            trace_println('${@FN}: skipping field "${field.name}" has an @[ignore] attribute')
            continue
        }
        doc := dc.fields[field.name] or { field.doc }
        short := field.shortest_match_name() or { '' }
        long := field.match_name

        // -f, --flag <type>
        mut flag_line := indent_flags_padding
        flag_line += if short != '' { '${short_delimiter}${short}' } else { '' }
        if !field.hints.has(.short_only) && long != '' {
            if short != '' {
                flag_line += ', '
            }
            flag_line += '${long_delimiter}${long}'
        }
        if dc.options.show.has(.flag_type) && field.type_name != 'bool' {
            if !field.hints.has(.can_repeat) {
                flag_line += ' <${field.type_name.replace('[]', '')}>'
            }
        }
        if dc.options.show.has(.flag_hint) {
            if field.hints.has(.is_array) {
                flag_line += ' (allowed multiple times)'
            }
            if field.hints.has(.can_repeat) {
                flag_line += ', ${short_delimiter}${short}${short}${short}... (can repeat)'
            }
        }
        flag_line_diff := flag_line.len - pad_desc
        if flag_line_diff < 0 {
            // This makes sure the description is put on a new line if the flag line is
            // longer than the padding.
            diff := -flag_line_diff
            line := flag_line + ' '.repeat(diff) +
                keep_at_max(doc, desc_max).replace('\n', '\n${empty_padding}')
            docs << line.trim_space_right()
        } else {
            docs << flag_line.trim_space_right()
            if doc != '' {
                line := empty_padding +
                    keep_at_max(doc, desc_max).replace('\n', '\n${empty_padding}')
                docs << line.trim_space_right()
            }
        }
        if !dc.options.compact {
            docs << ''
        }
    }
    // Look for custom flag entries starting with delimiter
    for entry, doc in dc.fields {
        if entry.starts_with(dc.delimiter) {
            flag_line_diff := entry.len - pad_desc + indent_flags
            if flag_line_diff < 0 {
                // This makes sure the description is put on a new line if the flag line is
                // longer than the padding.
                diff := -flag_line_diff
                line := indent_flags_padding + entry.trim(' ') + ' '.repeat(diff) +
                    keep_at_max(doc, desc_max).replace('\n', '\n${empty_padding}')
                docs << line.trim_space_right()
            } else {
                docs << indent_flags_padding + entry.trim(' ')
                line := empty_padding +
                    keep_at_max(doc, desc_max).replace('\n', '\n${empty_padding}')
                docs << line.trim_space_right()
            }
            if !dc.options.compact {
                docs << ''
            }
        }
    }
    if docs.len > 0 {
        if !dc.options.compact {
            // In non-compact mode the last item will be an empty line, delete it
            docs.delete_last()
        }
    }
    return docs
}

// keep_at_max returns `str` that is kept at a line width of `max` characters.
// User provided newlines is ignored in case the `str` has to be corrected to
// fit the provided `max` width value. Lines longer than `max` are not dealt with.
fn keep_at_max(str string, max int) string {
    safe_max := if max <= 0 { 1 } else { max }
    if str.len <= safe_max || str.count(' ') == 0 {
        return str
    }
    mut fitted := ''
    mut width := 0
    mut last_possible_break := str.index(' ') or { 0 }
    mut never_touched := true
    s := str.trim_space()
    for i, c in s {
        width++
        if c == ` ` {
            last_possible_break = i
        } else if c == `\n` {
            width = 0
        }
        if width == safe_max {
            never_touched = false
            fitted = s[..last_possible_break] + '\n'
            // At this point we are refitting the doc string so user provided newlines can not be kept
            // ... at least not without a tremendous increase in code complexity, that highly likely
            // will not suit all use-cases anyway.
            fitted +=
                keep_at_max(s[last_possible_break..].replace('\n', ' ').trim(' '), safe_max).trim(' ')
        } else if width > safe_max {
            break
        }
    }
    if never_touched {
        return str
    }
    return fitted
}

// to_struct returns `defaults` or a new instance of `T` that has the parsed flags from `input` mapped to the fields of struct `T`.
pub fn (fm FlagMapper) to_struct[T](defaults ?T) !T {
    // Generate T result
    mut result := defaults or { T{} }
    the_default := defaults or { T{} }

    $if T is $struct {
        struct_name := T.name.all_after_last('.')
        $for field in T.fields {
            if f := fm.field_map_flag[field.name] {
                assign_single_flag_value(mut result.$(field.name), the_default.$(field.name), f,
                    struct_name, field.name)!
            }
            for f in fm.array_field_map_flag[field.name] {
                append_multi_flag_value(mut result.$(field.name), f, field.name)!
            }
        }
    } $else {
        return error('the type `${T.name}` can not be decoded.')
    }

    return result
}

// map_v returns `true` if the V style flag in `flag_ctx` can be mapped to `field`.
// map_v adds data of the match in the internal structures for further processing if applicable
fn (mut fm FlagMapper) map_v(flag_ctx FlagContext, field StructField) !bool {
    flag_raw := flag_ctx.raw
    flag_name := flag_ctx.name
    pos := flag_ctx.pos
    used_delimiter := flag_ctx.delimiter
    next := flag_ctx.next

    if field.hints.has(.is_bool) {
        if flag_name == field.match_name || flag_name == field.short {
            arg := if flag_raw.contains('=') { flag_raw.all_after('=') } else { '' }
            if arg != '' {
                return error('flag `${flag_raw}` can not be assigned to bool field "${field.name}"')
            }
            trace_println('${@FN}: found match for (bool) ${fm.dbg_match(flag_ctx, field, 'true',
                '')}')
            fm.field_map_flag[field.name] = FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                pos:        pos
            }
            fm.handled_pos << pos
            return true
        }
    }

    if flag_name == field.match_name || flag_name == field.short {
        if field.hints.has(.is_array) {
            trace_println('${@FN}: found match for (V style multiple occurrences) ${fm.dbg_match(flag_ctx,
                field, next, '')}')
            fm.add_array_flag(field.name, FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                arg:        ?string(next)
                pos:        pos
            })
        } else {
            trace_println('${@FN}: found match for (V style) ${fm.dbg_match(flag_ctx, field, next,
                '')}')
            fm.field_map_flag[field.name] = FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                arg:        ?string(next)
                pos:        pos
            }
        }
        fm.handled_pos << pos
        fm.handled_pos << pos + 1 // arg
        return true
    }
    return false
}

// map_v_flag_parser_short returns `true` if the V `flag.FlagParser` short (-) flag in `flag_ctx` can be mapped to `field`.
// map_v_flag_parser_short adds data of the match in the internal structures for further processing if applicable
fn (mut fm FlagMapper) map_v_flag_parser_short(flag_ctx FlagContext, field StructField) !bool {
    flag_raw := flag_ctx.raw
    flag_name := flag_ctx.name
    pos := flag_ctx.pos
    used_delimiter := flag_ctx.delimiter
    next := flag_ctx.next

    if flag_name.len != 1 {
        return error('`${flag_raw}` is not supported in V `flag.FlagParser` (short) style parsing mode. Only single character flag names are supported. Use `-f value` instead')
    }

    if flag_raw.contains('=') {
        return error('`=` in flag `${flag_raw}` is not supported in V `flag.FlagParser` (short) style parsing mode. Use `-f value` instead')
    }

    if field.hints.has(.is_bool) {
        if flag_name == field.match_name || flag_name == field.short {
            trace_println('${@FN}: found match for (bool) ${fm.dbg_match(flag_ctx, field, 'true',
                '')}')
            fm.field_map_flag[field.name] = FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                pos:        pos
            }
            fm.handled_pos << pos
            return true
        }
    }

    if flag_name == field.match_name || flag_name == field.short {
        if field.hints.has(.is_array) {
            trace_println('${@FN}: found match for V (`flag.FlagParser` (short) style multiple occurrences) ${fm.dbg_match(flag_ctx,
                field, next, '')}')
            fm.add_array_flag(field.name, FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                arg:        ?string(next)
                pos:        pos
            })
        } else {
            trace_println('${@FN}: found match for V (`flag.FlagParser` (short) style) ${fm.dbg_match(flag_ctx,
                field, next, '')}')
            fm.field_map_flag[field.name] = FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                arg:        ?string(next)
                pos:        pos
            }
        }
        fm.handled_pos << pos
        fm.handled_pos << pos + 1 // arg
        return true
    }
    return false
}

// map_v_flag_parser_long returns `true` if the V `flag.FlagParser` long (--) style flag in `flag_ctx` can be mapped to `field`.
// map_v_flag_parser_long adds data of the match in the internal structures for further processing if applicable
fn (mut fm FlagMapper) map_v_flag_parser_long(flag_ctx FlagContext, field StructField) !bool {
    flag_raw := flag_ctx.raw
    flag_name := flag_ctx.name
    pos := flag_ctx.pos
    used_delimiter := flag_ctx.delimiter
    next := flag_ctx.next

    if flag_raw.contains('=') {
        return error('`=` in flag `${flag_raw}` is not supported in V `flag.FlagParser` (long) style parsing mode. Use `--flag value` instead')
    }

    if field.hints.has(.is_bool) {
        if flag_name == field.match_name {
            trace_println('${@FN}: found match for (bool) ${fm.dbg_match(flag_ctx, field, 'true',
                '')}')
            fm.field_map_flag[field.name] = FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                pos:        pos
            }
            fm.handled_pos << pos
            return true
        }
    }

    if flag_name == field.match_name || flag_name == field.short {
        if field.hints.has(.is_array) {
            trace_println('${@FN}: found match for (V `flag.FlagParser` (long) style multiple occurrences) ${fm.dbg_match(flag_ctx,
                field, next, '')}')
            fm.add_array_flag(field.name, FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                arg:        ?string(next)
                pos:        pos
            })
        } else {
            trace_println('${@FN}: found match for V (`flag.FlagParser` (long) style) ${fm.dbg_match(flag_ctx,
                field, next, '')}')
            fm.field_map_flag[field.name] = FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                arg:        ?string(next)
                pos:        pos
            }
        }
        fm.handled_pos << pos
        fm.handled_pos << pos + 1 // arg
        return true
    }
    return false
}

// map_go_flag_short returns `true` if the GO short style flag in `flag_ctx` can be mapped to `field`.
// map_go_flag_short adds data of the match in the internal structures for further processing if applicable
fn (mut fm FlagMapper) map_go_flag_short(flag_ctx FlagContext, field StructField) !bool {
    flag_raw := flag_ctx.raw
    flag_name := flag_ctx.name
    pos := flag_ctx.pos
    used_delimiter := flag_ctx.delimiter
    next := flag_ctx.next

    if field.hints.has(.is_bool) {
        if flag_name == field.match_name {
            arg := if flag_raw.contains('=') { flag_raw.all_after('=') } else { '' }
            if arg != '' {
                return error('flag `${flag_raw}` can not be assigned to bool field "${field.name}"')
            }
            trace_println('${@FN}: found match for (bool) ${fm.dbg_match(flag_ctx, field, 'true',
                '')}')
            fm.field_map_flag[field.name] = FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                pos:        pos
            }
            fm.handled_pos << pos
            return true
        }
    }

    if flag_name == field.match_name || flag_name == field.short {
        if field.hints.has(.is_array) {
            trace_println('${@FN}: found match for (GO short style multiple occurrences) ${fm.dbg_match(flag_ctx,
                field, next, '')}')
            fm.add_array_flag(field.name, FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                arg:        ?string(next)
                pos:        pos
            })
        } else {
            trace_println('${@FN}: found match for (GO short style) ${fm.dbg_match(flag_ctx, field,
                next, '')}')
            fm.field_map_flag[field.name] = FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                arg:        ?string(next)
                pos:        pos
            }
        }
        fm.handled_pos << pos
        fm.handled_pos << pos + 1 // arg
        return true
    }
    return false
}

// map_go_flag_long returns `true` if the GO long style flag in `flag_ctx` can be mapped to `field`.
// map_go_flag_long adds data of the match in the internal structures for further processing if applicable
fn (mut fm FlagMapper) map_go_flag_long(flag_ctx FlagContext, field StructField) !bool {
    flag_raw := flag_ctx.raw
    flag_name := flag_ctx.name
    pos := flag_ctx.pos
    used_delimiter := flag_ctx.delimiter

    if flag_name == field.match_name {
        if field.hints.has(.is_bool) {
            arg := if flag_raw.contains('=') { flag_raw.all_after('=') } else { '' }
            if arg != '' {
                return error('flag `${flag_raw}` can not be assigned to bool field "${field.name}"')
            }
            trace_println('${@FN}: found match for (bool) (GO `flag` style) ${fm.dbg_match(flag_ctx,
                field, 'true', '')}')
            fm.field_map_flag[field.name] = FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                pos:        pos
            }
            fm.handled_pos << pos
            return true
        }

        if !flag_raw.contains('=') {
            if field.hints.has(.is_int_type) && field.hints.has(.can_repeat) {
                return error('field `${field.name}` has @[repeats], only POSIX short style allows repeating')
            }
            return error('long delimiter `${used_delimiter}` flag `${flag_raw}` mapping to `${field.name}` in ${fm.config.style} style parsing mode, expects GO (GNU) style assignment. E.g.: --name=value')
        }

        arg := if flag_raw.contains('=') { flag_raw.all_after('=') } else { '' }
        if field.hints.has(.is_array) {
            trace_println('${@FN}: found match for (GO `flag` style multiple occurrences) ${fm.dbg_match(flag_ctx,
                field, arg, '')}')
            fm.add_array_flag(field.name, FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                arg:        ?string(arg)
                pos:        pos
            })
        } else {
            trace_println('${@FN}: found match for (GO `flag` style) ${fm.dbg_match(flag_ctx,
                field, arg, '')}')
            fm.field_map_flag[field.name] = FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                arg:        ?string(arg)
                pos:        pos
            }
        }
        fm.handled_pos << pos // NOTE: arg is part of the flag in GO (GNU) long style args
        return true
    }
    return false
}

// map_gnu_long returns `true` if the GNU (long) style flag in `flag_ctx` can be mapped to `field`.
// map_gnu_long adds data of the match in the internal structures for further processing if applicable
fn (mut fm FlagMapper) map_gnu_long(flag_ctx FlagContext, field StructField) !bool {
    flag_raw := flag_ctx.raw
    flag_name := flag_ctx.name
    pos := flag_ctx.pos
    used_delimiter := flag_ctx.delimiter

    if flag_name == field.match_name {
        if field.hints.has(.is_bool) {
            arg := if flag_raw.contains('=') { flag_raw.all_after('=') } else { '' }
            if arg != '' {
                return error('flag `${flag_raw}` can not be assigned to bool field "${field.name}"')
            }
            trace_println('${@FN}: found match for (bool) ${fm.dbg_match(flag_ctx, field, 'true',
                '')}')
            fm.field_map_flag[field.name] = FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                pos:        pos
            }
            fm.handled_pos << pos
            return true
        } else if fm.config.style in [.long, .short_long] && !flag_raw.contains('=') {
            if field.hints.has(.is_int_type) && field.hints.has(.can_repeat) {
                return error('field `${field.name}` has @[repeats], only POSIX short style allows repeating')
            }
            return error('long delimiter `${used_delimiter}` flag `${flag_raw}` mapping to `${field.name}` in ${fm.config.style} style parsing mode, expects GNU style assignment. E.g.: --name=value')
        }

        arg := if flag_raw.contains('=') { flag_raw.all_after('=') } else { '' }
        if field.hints.has(.is_array) {
            trace_println('${@FN}: found match for (GNU style multiple occurrences) ${fm.dbg_match(flag_ctx,
                field, arg, '')}')
            fm.add_array_flag(field.name, FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                arg:        ?string(arg)
                pos:        pos
            })
        } else {
            trace_println('${@FN}: found match for (GNU style) ${fm.dbg_match(flag_ctx, field, arg,
                '')}')
            fm.field_map_flag[field.name] = FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                arg:        ?string(arg)
                pos:        pos
            }
        }
        fm.handled_pos << pos // NOTE: arg is part of the flag in GNU long style args
        return true
    }
    return false
}

// map_posix_short_cluster looks for multiple combined short flags and optional
// tail arguments e.g. `-yxz( a)` = `-y -x -z( a)` and maps them to the respective struct fields.
// map_posix_short_cluster adds data of the match in the internal structures for further processing if applicable.
fn (mut fm FlagMapper) map_posix_short_cluster(flag_ctx FlagContext) ! {
    flag_name := flag_ctx.name
    if flag_name.len <= 1 {
        return
    }
    first_letter := flag_name[0].ascii_str()
    // Do not handle repeated-only bundles like `-vv`; `map_posix_short` does that.
    if flag_name.count(first_letter) == flag_name.len {
        return
    }

    if flag_name.len > 1 {
        mut split := flag_name.split('')
        mut matched_fields := map[string]StructField{}
        for mflag in split {
            mut matched := false
            for _, field in fm.si.fields {
                if smatch_name := field.shortest_match_name() {
                    if mflag == smatch_name {
                        trace_println('${@FN}: cluster flag `${mflag}` matches field `${smatch_name}`')
                        matched_fields[mflag] = field
                        matched = true
                    }
                }
            }
            if !matched {
                break
            }
        }

        if matched_fields.len == 0 {
            return
        }

        // Iterate `split` instead of `matched_fields` since the order of appearance has significance
        for i := 0; i < split.len; i++ {
            mflag := split[i]
            if field := matched_fields[mflag] {
                // trace_println('${@FN}: ${mflag} matches ${field.name}')
                mf := FlagData{
                    raw:        flag_ctx.raw
                    field_name: field.name
                    delimiter:  flag_ctx.delimiter
                    name:       mflag
                    pos:        flag_ctx.pos
                }
                if field.hints.has(.is_bool) {
                    trace_println('${@FN}: found match for (bool) ${fm.dbg_match(flag_ctx, field,
                        'true', '')}')
                    fm.field_map_flag[mf.field_name] = mf
                    fm.handled_pos << flag_ctx.pos
                } else if field.hints.has(.can_repeat) {
                    repeats := if existing := fm.field_map_flag[mf.field_name] {
                        existing.repeats + 1
                    } else {
                        1
                    }
                    trace_println('${@FN}: found match for (repeatable cluster) ${fm.dbg_match(flag_ctx,
                        field, '${repeats}', '')}')
                    fm.field_map_flag[mf.field_name] = FlagData{
                        ...mf
                        repeats: repeats
                    }
                    fm.handled_pos << flag_ctx.pos
                } else {
                    mut arg := split[i + 1..].clone().join('')
                    mut next_is_used := false
                    if arg == '' {
                        arg = flag_ctx.next
                        if arg != '' {
                            next_is_used = true
                        }
                    }
                    if field.hints.has(.is_array) {
                        fm.add_array_flag(mf.field_name, FlagData{
                            ...mf
                            arg: ?string(arg)
                        })
                        trace_println('${@FN}: found match for (array) ${fm.dbg_match(flag_ctx,
                            field, arg, '')}')
                    } else {
                        trace_println('${@FN}: found match for (other) ${fm.dbg_match(flag_ctx,
                            field, arg, '')}')
                        fm.field_map_flag[mf.field_name] = FlagData{
                            ...mf
                            arg: ?string(arg)
                        }
                    }
                    fm.handled_pos << flag_ctx.pos
                    if next_is_used {
                        fm.handled_pos << flag_ctx.pos + 1 // next
                    }
                    break
                }
            }
        }
    }
}

// map_posix_short returns `true` if the POSIX (short) style flag in `flag_ctx` can be mapped to `field`.
// map_posix_short adds data of the match in the internal structures for further processing if applicable
// map_posix_short handles, amoung other things the mapping of repeatable short flags. E.g.: `-vvv vvv`
fn (mut fm FlagMapper) map_posix_short(flag_ctx FlagContext, field StructField) !bool {
    flag_raw := flag_ctx.raw
    mut flag_name := flag_ctx.name
    pos := flag_ctx.pos
    used_delimiter := flag_ctx.delimiter
    mut next := flag_ctx.next
    struct_name := fm.si.name

    first_letter := flag_name.split('')[0]
    next_first_letter := if next != '' { next.split('')[0] } else { '' }
    count_of_first_letter_repeats := flag_name.count(first_letter)
    count_of_next_first_letter_repeats := next.count(next_first_letter)

    if field.hints.has(.is_bool) {
        if flag_name == field.match_name {
            arg := if flag_raw.contains('=') { flag_raw.all_after('=') } else { '' }
            if arg != '' {
                return error('flag `${flag_raw}` can not be assigned to bool field "${field.name}"')
            }
            trace_println('${@FN}: found match for (bool) ${fm.dbg_match(flag_ctx, field, 'true',
                '')}')
            fm.field_map_flag[field.name] = FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                pos:        pos
            }
            fm.handled_pos << pos
            return true
        }

        if field.short == flag_name {
            trace_println('${@FN}: found match for (bool) ${fm.dbg_match(flag_ctx, field, 'true',
                '')}')
            fm.field_map_flag[field.name] = FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                pos:        pos
            }
            fm.handled_pos << pos
            return true
        }
    }

    if first_letter == field.short {
        // `-vvvvv`, `-vv vvv` or `-v vvvv`
        if field.hints.has(.can_repeat) {
            mut do_continue := false
            if count_of_first_letter_repeats == flag_name.len {
                trace_println('${@FN}: found match for (repeatable) ${fm.dbg_match(flag_ctx, field,
                    'true', '')}')
                fm.field_map_flag[field.name] = FlagData{
                    raw:        flag_raw
                    field_name: field.name
                    delimiter:  used_delimiter
                    name:       flag_name
                    pos:        pos
                    repeats:    count_of_first_letter_repeats
                }
                fm.handled_pos << pos
                do_continue = true

                if next_first_letter == first_letter
                    && count_of_next_first_letter_repeats == next.len {
                    trace_println('${@FN}: field "${field.name}" allow repeats and ${flag_raw} ${next} repeats ${
                        count_of_next_first_letter_repeats + count_of_first_letter_repeats} times (via argument)')
                    fm.field_map_flag[field.name] = FlagData{
                        raw:        flag_raw
                        field_name: field.name
                        delimiter:  used_delimiter
                        name:       flag_name
                        pos:        pos
                        repeats:    count_of_next_first_letter_repeats +
                            count_of_first_letter_repeats
                    }
                    fm.handled_pos << pos
                    fm.handled_pos << pos + 1 // next
                    do_continue = true
                } else {
                    trace_println('${@FN}: field "${field.name}" allow repeats and ${flag_raw} repeats ${count_of_first_letter_repeats} times')
                }
                if do_continue {
                    return true
                }
            }
        } else if field.hints.has(.is_array) {
            split := flag_name.trim_string_left(field.short)
            mut next_is_handled := true
            if split != '' {
                next = split
                flag_name = flag_name.trim_string_right(split)
                next_is_handled = false
            }

            if next == '' {
                return error('flag "${flag_raw}" expects an argument')
            }
            trace_println('${@FN}: found match for (multiple occurrences) ${fm.dbg_match(flag_ctx,
                field, next, '')}')

            fm.add_array_flag(field.name, FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                arg:        ?string(next)
                pos:        pos
            })
            fm.handled_pos << pos
            if next_is_handled {
                fm.handled_pos << pos + 1 // next
            }
            return true
        } else if !flag_ctx.next.starts_with(used_delimiter) {
            if field.short == flag_name {
                trace_println('${@FN}: found match for (${field.type_name}) ${fm.dbg_match(flag_ctx,
                    field, next, '')}')
                fm.field_map_flag[field.name] = FlagData{
                    raw:        flag_raw
                    field_name: field.name
                    delimiter:  used_delimiter
                    name:       flag_name
                    arg:        ?string(next)
                    pos:        pos
                }
                fm.handled_pos << pos
                fm.handled_pos << pos + 1 // next
                return true
            }
        }
    }
    if (fm.config.style == .short || field.hints.has(.short_only)) && first_letter == field.short {
        split := flag_name.trim_string_left(field.short)
        mut next_is_handled := true
        if split != '' {
            next = split
            flag_name = flag_name.trim_string_right(split)
            next_is_handled = false
        }

        if next == '' {
            return error('flag "${flag_raw}" expects an argument')
        }
        trace_println('${@FN}: found match for (short only) ${struct_name}.${field.name} (${field.match_name}) = ${field.short} = ${next}')

        fm.field_map_flag[field.name] = FlagData{
            raw:        flag_raw
            field_name: field.name
            delimiter:  used_delimiter
            name:       flag_name
            arg:        ?string(next)
            pos:        pos
            repeats:    count_of_first_letter_repeats
        }
        fm.handled_pos << pos
        if next_is_handled {
            fm.handled_pos << pos + 1 // next
        }
        return true
    } else if flag_name == field.match_name && !(field.hints.has(.short_only)
        && flag_name == field.short) {
        trace_println('${@FN}: found match for (repeats) ${fm.dbg_match(flag_ctx, field, next, '')}')
        if next == '' {
            return error('flag "${flag_raw}" expects an argument')
        }
        fm.field_map_flag[field.name] = FlagData{
            raw:        flag_raw
            field_name: field.name
            delimiter:  used_delimiter
            name:       flag_name
            arg:        ?string(next)
            pos:        pos
            repeats:    count_of_first_letter_repeats
        }
        fm.handled_pos << pos
        fm.handled_pos << pos + 1 // next
        return true
    }
    return false
}

// map_cmd_exe returns `true` if the CMD.EXE style flag in `flag_ctx` can be mapped to `field`.
// map_cmd_exe adds data of the match in the internal structures for further processing if applicable
fn (mut fm FlagMapper) map_cmd_exe(flag_ctx FlagContext, field StructField) !bool {
    flag_raw := flag_ctx.raw
    flag_name := flag_ctx.name
    pos := flag_ctx.pos
    used_delimiter := flag_ctx.delimiter
    next := flag_ctx.next

    if flag_name == field.match_name {
        if field.hints.has(.is_bool) {
            trace_println('${@FN}: found (long) match for (bool) (CMD.EXE style) ${fm.dbg_match(flag_ctx,
                field, 'true', '')}')
            fm.field_map_flag[field.name] = FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                pos:        pos
            }
            fm.handled_pos << pos
            return true
        }
        // Not sure original CMD.EXE flags supported multiple flags with same name??
        if field.hints.has(.is_array) {
            trace_println('${@FN}: found match for (CMD.EXE style multiple occurrences) ${fm.dbg_match(flag_ctx,
                field, next, '')}')
            fm.add_array_flag(field.name, FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                arg:        ?string(next)
                pos:        pos
            })
        } else {
            trace_println('${@FN}: found match for (CMD.EXE style) ${fm.dbg_match(flag_ctx, field,
                next, '')}')
            fm.field_map_flag[field.name] = FlagData{
                raw:        flag_raw
                field_name: field.name
                delimiter:  used_delimiter
                name:       flag_name
                arg:        ?string(next)
                pos:        pos
            }
        }
        fm.handled_pos << pos
        fm.handled_pos << pos + 1 // arg
        return true
    }
    // Not aware of CMD.EXE flags longer than one (ASCII??) character
    if shortest_match_name := field.shortest_match_name() {
        if flag_name == shortest_match_name {
            if field.hints.has(.is_bool) {
                trace_println('${@FN}: found match for (bool) (CMD.EXE style) ${fm.dbg_match(flag_ctx,
                    field, 'true', '')}')
                fm.field_map_flag[field.name] = FlagData{
                    raw:        flag_raw
                    field_name: field.name
                    delimiter:  used_delimiter
                    name:       flag_name
                    pos:        pos
                }
                fm.handled_pos << pos
                return true
            }

            // Not sure original CMD.EXE flags supported multiple flags with same name??
            if field.hints.has(.is_array) {
                trace_println('${@FN}: found match for (CMD.EXE style multiple occurrences) ${fm.dbg_match(flag_ctx,
                    field, next, '')}')
                fm.add_array_flag(field.name, FlagData{
                    raw:        flag_raw
                    field_name: field.name
                    delimiter:  used_delimiter
                    name:       flag_name
                    arg:        ?string(next)
                    pos:        pos
                })
            } else {
                trace_println('${@FN}: found match for (CMD.EXE style) ${fm.dbg_match(flag_ctx,
                    field, next, '')}')
                fm.field_map_flag[field.name] = FlagData{
                    raw:        flag_raw
                    field_name: field.name
                    delimiter:  used_delimiter
                    name:       flag_name
                    arg:        ?string(next)
                    pos:        pos
                }
            }
            fm.handled_pos << pos
            fm.handled_pos << pos + 1 // arg
            return true
        }
    }
    return false
}

// parsed_flags returns all parsed flags in order of position.
pub fn (fm FlagMapper) parsed_flags() []FlagData {
    mut flags := []FlagData{}
    for _, f in fm.field_map_flag {
        flags << f
    }
    for _, arr in fm.array_field_map_flag {
        for f in arr {
            flags << f
        }
    }
    flags.sort_with_compare(fn (a &FlagData, b &FlagData) int {
        if a.pos != b.pos {
            return if a.pos < b.pos { -1 } else { 1 }
        }
        return if a.name < b.name {
            -1
        } else if a.name > b.name {
            1
        } else {
            0
        }
    })
    return flags
}

// `handled_positions` returns unique, sorted position indices from the input args that were consumed during parsing.
pub fn (fm FlagMapper) handled_positions() []int {
    mut seen := map[int]bool{}
    mut result := []int{}
    for p in fm.handled_pos {
        if p !in seen {
            seen[p] = true
            result << p
        }
    }
    result.sort(a < b)
    return result
}