command_parse.go

package cli

import (
	"fmt"
	"slices"
	"strings"
	"unicode"
	"unicode/utf8"
)

const (
	providedButNotDefinedErrMsg = "flag provided but not defined: -"
	argumentNotProvidedErrMsg   = "flag needs an argument: "
)

// flagFromError tries to parse a provided flag from an error message. If the
// parsing fails, it returns the input error and an empty string
func flagFromError(err error) (string, error) {
	trimmed, ok := strings.CutPrefix(err.Error(), providedButNotDefinedErrMsg)
	if !ok {
		return "", err
	}
	return trimmed, nil
}

func (cmd *Command) parseFlags(args Args) (Args, error) {
	tracef("parsing flags from arguments %[1]q (cmd=%[2]q)", args, cmd.Name)

	cmd.setFlags = map[Flag]struct{}{}
	cmd.appliedFlags = cmd.allFlags()

	tracef("walking command lineage for persistent flags (cmd=%[1]q)", cmd.Name)

	for pCmd := cmd.parent; pCmd != nil; pCmd = pCmd.parent {
		tracef(
			"checking ancestor command=%[1]q for persistent flags (cmd=%[2]q)",
			pCmd.Name, cmd.Name,
		)

		for _, fl := range pCmd.allFlags() {
			flNames := fl.Names()

			pfl, ok := fl.(LocalFlag)
			if !ok || pfl.IsLocal() {
				tracef("skipping non-persistent flag %[1]q (cmd=%[2]q)", flNames, cmd.Name)
				continue
			}

			tracef(
				"checking for applying persistent flag=%[1]q pCmd=%[2]q (cmd=%[3]q)",
				flNames, pCmd.Name, cmd.Name,
			)

			applyPersistentFlag := true

			for _, name := range flNames {
				if cmd.lFlag(name) != nil {
					applyPersistentFlag = false
					break
				}
			}

			if !applyPersistentFlag {
				tracef("not applying as persistent flag=%[1]q (cmd=%[2]q)", flNames, cmd.Name)
				continue
			}

			tracef("applying as persistent flag=%[1]q (cmd=%[2]q)", flNames, cmd.Name)

			tracef("appending to applied flags flag=%[1]q (cmd=%[2]q)", flNames, cmd.Name)
			cmd.appliedFlags = append(cmd.appliedFlags, fl)
		}
	}

	tracef("parsing flags iteratively tail=%[1]q (cmd=%[2]q)", args.Tail(), cmd.Name)
	defer tracef("done parsing flags (cmd=%[1]q)", cmd.Name)

	posArgs := []string{}
	for rargs := args.Slice(); len(rargs) > 0; rargs = rargs[1:] {
		tracef("rearrange:1 (cmd=%[1]q) %[2]q", cmd.Name, rargs)

		// Check if we've reached the Nth argument and should stop flag parsing.
		// This comes before the empty arg and "--" checks below, so that an
		// empty arg or "--" after the Nth argument is passed through as is.
		if cmd.StopOnNthArg != nil && len(posArgs) == *cmd.StopOnNthArg {
			// Append current arg and all remaining args without parsing
			posArgs = append(posArgs, rargs[0:]...)
			return &stringSliceArgs{posArgs}, nil
		}

		firstArg := strings.TrimSpace(rargs[0])
		if len(firstArg) == 0 {
			posArgs = append(posArgs, rargs[0])
			continue
		}

		// stop parsing once we see a "--"
		if firstArg == "--" {
			// In shell completion mode, preserve "--" so that completion can detect
			// when the user is completing "--" itself vs. completing after "--"
			if cmd.Root().shellCompletion {
				posArgs = append(posArgs, firstArg)
			}
			posArgs = append(posArgs, rargs[1:]...)
			return &stringSliceArgs{posArgs}, nil
		}

		// handle positional args
		if firstArg[0] != '-' {
			// positional argument probably
			tracef("rearrange-3 (cmd=%[1]q) check %[2]q", cmd.Name, firstArg)

			// if there is a command by that name let the command handle the
			// rest of the parsing
			if cmd.Command(firstArg) != nil {
				posArgs = append(posArgs, rargs...)
				return &stringSliceArgs{posArgs}, nil
			}

			// firstArg is a trimmed copy that classifies the argument; the
			// argument itself is what the action receives, byte for byte.
			posArgs = append(posArgs, rargs[0])
			continue
		}

		numMinuses := 1
		if firstArg == "-" {
			posArgs = append(posArgs, rargs[0])
			continue
		}

		shortOptionHandling := cmd.useShortOptionHandling()

		// stop parsing -- as short flags
		if firstArg[1] == '-' {
			numMinuses++
			shortOptionHandling = false
		} else if firstRune, _ := utf8.DecodeRuneInString(firstArg[1:]); !unicode.IsLetter(firstRune) &&
			!cmd.startsWithAppliedFlag(firstArg[1:], firstRune, shortOptionHandling) {
			// this is not a flag, e.g. a negative number
			tracef("parseFlags not a unicode letter. Stop parsing")
			posArgs = append(posArgs, rargs...)
			return &stringSliceArgs{posArgs}, nil
		}

		tracef("parseFlags (shortOptionHandling=%[1]q)", shortOptionHandling)

		flagName := firstArg[numMinuses:]
		flagVal := ""
		tracef("flagName:1 (fName=%[1]q)", flagName)
		flagName, _, valFromEqual := strings.Cut(flagName, "=")
		if valFromEqual {
			// Classify the flag using the trimmed token, but leave value
			// whitespace handling to the flag's value parser.
			_, flagVal, _ = strings.Cut(rargs[0], "=")
		}

		tracef("flagName:2 (fName=%[1]q) (fVal=%[2]q)", flagName, flagVal)

		f := cmd.lookupAppliedFlag(flagName)
		// found a flag matching given flagName
		if f != nil {
			tracef("Trying flag type (fName=%[1]q) (type=%[2]T)", flagName, f)
			if fb, ok := f.(boolFlag); ok && fb.IsBoolFlag() {
				if flagVal == "" && !valFromEqual {
					flagVal = "true"
				}
				tracef("parse Apply bool flag (fName=%[1]q) (fVal=%[2]q)", flagName, flagVal)
				if err := cmd.set(flagName, f, flagVal); err != nil {
					return &stringSliceArgs{posArgs}, err
				}
				continue
			}

			tracef("processing non bool flag (fName=%[1]q)", flagName)
			// not a bool flag so need to get the next arg
			if flagVal == "" && !valFromEqual {
				if len(rargs) == 1 {
					// In shell completion mode, preserve the flag so that DefaultCompleteWithFlags can use it
					// as lastArg and offer suggestions for it.
					if cmd.Root().shellCompletion {
						posArgs = append(posArgs, rargs...)
						return &stringSliceArgs{posArgs}, nil
					}
					return &stringSliceArgs{posArgs}, fmt.Errorf("%s%s", argumentNotProvidedErrMsg, firstArg)
				}
				flagVal = rargs[1]
				rargs = rargs[1:]
			}

			tracef("setting non bool flag (fName=%[1]q) (fVal=%[2]q)", flagName, flagVal)
			if err := cmd.set(flagName, f, flagVal); err != nil {
				return &stringSliceArgs{posArgs}, err
			}

			continue
		}

		// no flag lookup found and short handling is disabled
		if !shortOptionHandling {
			// In shell completion mode, preserve the partial flag so that DefaultCompleteWithFlags can use it
			// as lastArg and offer suggestions that match the prefix.
			if cmd.Root().shellCompletion {
				posArgs = append(posArgs, rargs...)
				return &stringSliceArgs{posArgs}, nil
			}
			// When DefaultCommand is set, pass unknown flags through as positional args
			// so the default command can handle them (fixes #2249)
			if cmd.DefaultCommand != "" {
				posArgs = append(posArgs, rargs...)
				return &stringSliceArgs{posArgs}, nil
			}
			return &stringSliceArgs{posArgs}, fmt.Errorf("%s%s", providedButNotDefinedErrMsg, flagName)
		}

		// ranging over flagName yields byte offsets, so the last flag starts
		// where its rune starts, which is not len-1 for a multi-byte rune
		_, lastSize := utf8.DecodeLastRuneInString(flagName)
		lastIndex := len(flagName) - lastSize

		// every flag of the group has to exist before any of them is set,
		// otherwise a group holding an unknown flag is reported by whichever
		// of its flags happens to be examined first
		for index, c := range flagName {
			if sf := cmd.lookupAppliedFlag(string(c)); sf == nil {
				if index == 0 && cmd.DefaultCommand != "" {
					posArgs = append(posArgs, rargs...)
					return &stringSliceArgs{posArgs}, nil
				}
				return &stringSliceArgs{posArgs}, fmt.Errorf("%s%s", providedButNotDefinedErrMsg, flagName)
			}
		}

		// try to split the flags
		for index, c := range flagName {
			tracef("processing flag (fName=%[1]q)", string(c))
			// the check above has already found every flag of the group
			sf := cmd.lookupAppliedFlag(string(c))
			if fb, ok := sf.(boolFlag); ok && fb.IsBoolFlag() {
				// the value after "=" belongs to the last flag of the group,
				// so a bool flag before it is just set
				fv := "true"
				if index == lastIndex && valFromEqual {
					fv = flagVal
				}
				if err := cmd.set(string(c), sf, fv); err != nil {
					tracef("processing flag.2 (fName=%[1]q)", string(c))
					return &stringSliceArgs{posArgs}, err
				}
			} else if index == lastIndex { // last flag can take an arg
				// as with a single flag, an explicit "=" with nothing after
				// it is an empty value, not a request to read the next arg
				if flagVal == "" && !valFromEqual {
					if len(rargs) == 1 {
						return &stringSliceArgs{posArgs}, fmt.Errorf("%s%s", argumentNotProvidedErrMsg, string(c))
					}
					flagVal = rargs[1]
					rargs = rargs[1:]
				}
				tracef("parseFlags (flagName %[1]q) (flagVal %[2]q)", flagName, flagVal)
				if err := cmd.set(string(c), sf, flagVal); err != nil {
					tracef("processing flag.4 (fName=%[1]q)", string(c))
					return &stringSliceArgs{posArgs}, err
				}
			} else {
				// only the last flag of a group can take an argument, so a flag
				// that needs one has nothing to read it from here
				tracef("processing flag.5 (fName=%[1]q)", string(c))
				return &stringSliceArgs{posArgs}, fmt.Errorf("%s%s", argumentNotProvidedErrMsg, string(c))
			}
		}
	}

	tracef("returning-2 (cmd=%[1]q) args %[2]q", cmd.Name, posArgs)
	return &stringSliceArgs{posArgs}, nil
}

// startsWithAppliedFlag reports whether a single-dash argument, given without
// its dash, names a flag even though it does not start with a letter, as
// "-4" does when a flag is named "4". With short option handling, a group
// such as "-46" names a flag when its first flag does.
func (cmd *Command) startsWithAppliedFlag(arg string, firstRune rune, shortOptionHandling bool) bool {
	name, _, _ := strings.Cut(arg, "=")
	// lookupAppliedFlag would call InvalidFlagAccessHandler for an
	// argument that names no flag, such as the negative number "-5"
	for _, f := range cmd.appliedFlags {
		names := f.Names()
		if slices.Contains(names, name) ||
			(shortOptionHandling && slices.Contains(names, string(firstRune))) {
			return true
		}
	}
	return false
}